@scayver/specshot-mcp-server 0.14.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,15 +5,17 @@
5
5
  // which fails whenever the two differ. To regenerate after changing the source:
6
6
  // cd apps/web && SPECSHOT_WRITE_GENERATED=1 npx vitest run src/lib/__tests__/mcp-stdio-sync.test.ts
7
7
  /** The connect-time instructions: the design law on one screen, then the short workflow and the skills. */
8
- export const CONNECT_INSTRUCTIONS = `Build full-fidelity, approvable website designs, never gray placeholders or bare skeletons. SAVE WHOLE PAGES, never a lone section or component: header, every section in order, footer. Assemble the page, then save it once: every save REPLACES the page, so saving only the part you changed deletes the rest. Read the project first (get_wireframe_context): use its real brand tokens, approved copy, and references. Its brief opens with CLIENT RULES, the client's and the agency's own instructions: follow every one. They beat every default here, never the boundary against copying another company's work or the anti-slop bans. STUDY every inspiration image before you build. Real SVG icons, the client's light or dark choice (both when unset), WCAG AA. FLUID RESPONSIVE IS THE LAW: correct at EVERY width, not three: clamp() type and space, auto-fit grids, min-width:0 on flex and grid children, container queries for components. NO AI TELLS: no Inter, Roboto, Arial, Geist, Fraunces, Plus Jakarta Sans or Space Grotesk by reflex (faces from the brand, then the references), no italic serif hero, no label above a heading by reflex, no purple-to-cyan gradient, no radial glow, never pure #000/#fff, no gray-on-color, no gradient text, no side-tab border, no cards nested in cards, no row of equal cards, no bounce easing, no emoji icons, no semicolons or em dashes in copy. Design every state (hover, focus, loading, empty, error) on its component, and show only the default state on the page. Inline all CSS and fonts: the preview strips external ones and runs no script. REAL IMAGES come from one source only: a placeableUrl in get_wireframe_context, on the client's own assets and the project's generated images. A reference captured from somebody else's page has placeableUrl null on purpose: study it and BUILD the section, never ship a picture of another company's page. Any other image URL is still stripped to a gray box. NUMBERS: body text at least 1rem, UI text never under 0.6875rem, line-height 1.5-1.7, 65-75 characters per line, at least a 1.25 type scale, headlines 2-3 lines, dvh never vh, touch targets at least 2.75rem. NEVER a placeholder comment in place of markup: a page with "rest of sections here" where its footer belongs is broken. PREMIUM AND ALIVE: a different layout per section and a bento on a home page, one content edge, one theme, a layered hero visual with a floating chip, imagery in the hero and two more sections (image spots with data-ss-image, data-ss-aspect and data-ss-alt over a drawn fallback, never a shape-built scene or grain), layered --shadow-1 to --shadow-4, embedded fonts, a load entrance, safe scroll reveals (@media screen, no-preference, @supports), two to four slow moving figures, lift, press and focus, transform and opacity only, headings that make claims. Call the premium_craft prompt before building, and the build_a_page prompt for the full standard.
8
+ export const CONNECT_INSTRUCTIONS = `BEFORE ANY WORK ON A PROJECT: call get_agent_briefing with its projectId and read every entry it lists, every part, with get_skill: the process, the design law, the clean Etch build and the skills for the project's stage. Read it again when its knowledgeVersion changes.
9
+
10
+ Build full-fidelity, approvable website designs, never gray placeholders or bare skeletons. SAVE WHOLE PAGES, never a lone section or component: header, every section in order, footer. Assemble the page, then save it once: every save REPLACES the page, so saving only the part you changed deletes the rest. Read the project first (get_wireframe_context): use its real brand tokens, approved copy, and references. Its brief opens with CLIENT RULES, the client's and the agency's own instructions: follow every one. They beat every default here, never the boundary against copying another company's work or the anti-slop bans. STUDY every inspiration image before you build. Real SVG icons, the client's light or dark choice (both when unset), WCAG AA. FLUID RESPONSIVE IS THE LAW: correct at EVERY width, not three: clamp() type and space, auto-fit grids, min-width:0 on flex and grid children, container queries for components. NO AI TELLS: no Inter, Roboto, Arial, Geist, Fraunces, Plus Jakarta Sans or Space Grotesk by reflex (faces from the brand, then the references), no italic serif hero, no label above a heading by reflex, no purple-to-cyan gradient, no radial glow, never pure #000/#fff, no gray-on-color, no gradient text, no side-tab border, no cards nested in cards, no row of equal cards, no bounce easing, no emoji icons, no semicolons or em dashes in copy. Design every state (hover, focus, loading, empty, error) on its component, and show only the default state on the page. Inline all CSS and fonts: the preview strips external ones and runs no script. REAL IMAGES come from one source only: a placeableUrl in get_wireframe_context, on the client's own assets and the project's generated images. A reference captured from somebody else's page has placeableUrl null on purpose: study it and BUILD the section, never ship a picture of another company's page. Any other image URL is still stripped to a gray box. NUMBERS: body text at least 1rem, UI text never under 0.6875rem, line-height 1.5-1.7, 65-75 characters per line, at least a 1.25 type scale, headlines 2-3 lines, dvh never vh, touch targets at least 2.75rem. NEVER a placeholder comment in place of markup: a page with "rest of sections here" where its footer belongs is broken. PREMIUM AND ALIVE: a different layout per section and a bento on a home page, one content edge, one theme, a layered hero visual with a floating chip, imagery in the hero and two more sections (image spots with data-ss-image, data-ss-aspect and data-ss-alt over a drawn fallback, never a shape-built scene or grain), layered --shadow-1 to --shadow-4, embedded fonts, a load entrance, safe scroll reveals (@media screen, no-preference, @supports), two to four slow moving figures, lift, press and focus, transform and opacity only, headings that make claims. Call the premium_craft prompt before building, and the build_a_page prompt for the full standard.
9
11
 
10
12
  TOKENS: one :root block with the canonical names, every value read as var(--name, literal). Type --step--1 to --step-6 and space --space-3xs to --space-3xl, each a clamp() from 360px to 1440px. Section padding is --pad-open or --pad-dense only, equal above and below; --gutter, --content, --measure; --radius-s/m/l/pill; --shadow-1 to --shadow-4 (layered); --dur-1 to --dur-5, --stagger, --ease-out, --ease-in-out; color roles --paper, --paper-2, --ink, --ink-2, --ink-3, --line, --accent (+ -hover, -quiet), --on-accent, --night, --on-night; faces --font-display and --font-text from the brand, then the references. No raw px or hex outside :root. Fluid first: a breakpoint only where the layout truly changes.
11
13
 
12
- STRUCTURE: anything repeated twice or more (cards, tiers, FAQ items, testimonials, nav items, buttons) is a component: data-component="PricingTier" (PascalCase) on each instance's root, data-prop="title" (camelCase) on what varies (data-prop-type url, image, or boolean with data-prop-class for a modifier), data-slot="actions" on child content that differs, data-optional on a prop some instances leave empty, and data-loop="tiers" on the container of a list of instances. Everything unmarked is identical in every instance. One BEM block per component (.pricing-tier), states as .block.is-open, no invented utilities, no inline styles, no layout that depends on position. Fluid: never px font sizes, @media only for page layout, no fixed widths over 20rem, text capped in ch, img with width and height or aspect-ratio. Components read semantic tokens, never raw values.
14
+ CONTENT MODEL FIRST: two or more pages that do one job (docs, blog, changelog, legal, services) are a content type, never plain Pages. A type's single design marks data-bind="title", data-bind="field:<key>" and data-bind="content" on the body; its archive puts data-loop="main" on its list with one card. The header and footer are kit components. STRUCTURE: anything repeated twice or more (cards, tiers, FAQ items) is a component: data-component="PricingTier" (PascalCase) on each instance's root, data-prop="title" (camelCase) on what varies (data-prop-type url, image, boolean with data-prop-class, or attr with data-prop-attr), data-slot="actions" on child content that differs, data-optional on a prop some instances leave empty, and data-loop="tiers" on the container of a list of instances. Everything unmarked is identical in every instance. One BEM block per component (.pricing-tier), states as .block.is-open, no invented utilities, no inline styles, no layout that depends on position. Fluid: never px font sizes, @media only for page layout, no fixed widths over 20rem, text capped in ch, img with width and height or aspect-ratio. Components read semantic tokens, never raw values.
13
15
 
14
- ETCH-READY: one class per rule with BEM names (block__element--modifier), no tag selectors inside @supports, @container or @layer, keyframes named for their block (chart-grow, never fadeIn), dark theme through prefers-color-scheme or a class on the design's own root (never :root[data-theme] or html[data-theme]), no html font-size, no #id selectors, no !important outside reduced motion, tokens declared once in :root with the canonical names (the export prefixes them and maps them to ACSS where the site runs it, so never write ACSS names by hand), images only from a placeableUrl, diagrams and icons as inline SVG, one root wrapper. The agency's Etch rules: flat BEM one level deep (never a__b__c), a repeated card its own block (.service-card) whose title heading holds its link (no Read more links), one custom media name per @media, no :has() inside :has(), every @keyframes at the top level of the CSS, SVG data URIs percent-encoded (%3Csvg), single quotes inside Etch expressions ({item.title.split(' ')}).
16
+ ETCH-READY: one class per rule with BEM names (block__element--modifier), no tag selectors inside @supports, @container or @layer, keyframes named for their block (chart-grow, never fadeIn), dark theme by prefers-color-scheme or a class on the section (never :root[data-theme]), no html font-size, no #id selectors, no !important outside reduced motion, tokens declared once in :root with the canonical names (never write ACSS names by hand: the export maps them), sections side by side in main, one container each, never wrapped or nested. Flat BEM one level deep (never a__b__c), a repeated card its own block (.service-card) whose title heading holds its link (no Read more links), one custom media name per @media, no :has() inside :has(), @keyframes at the top level, SVG data URIs percent-encoded (%3Csvg), single quotes inside Etch expressions.
15
17
 
16
- LAW CHECK: every save returns designLaw (score 0 to 100, findings with code, severity and fix). BLOCK, clear slop or a sure Etch break to fix before anything is called ready: emoji-icon, placeholder-image, placeholder-copy, text-contrast, fluid-type (no fluid type at all), grain, hidden-reveal, etch-custom-media, etch-expression-quotes. WARN: fluid-space, token-density, off-token-color, radius-sprawl, generic-gradient, center-everything, border-and-shadow, nested-cards, side-tab, eyebrow-sprawl, buzzwords, form-controls, pure-black-white, broad-will-change, mask-without-size, custom-cursor, italic-serif-hero, banned-face, svg-scene, radial-glow, dark-section, equal-cards, section-spacing, same-entrance, reveal-form, marquee, endless-animation, linear-easing, layout-motion, global-motion-reset, image-loading, unsourced-claim (a claim the brief does not give: mark it [GAP: what is missing], or [UNVERIFIED: what] when stated but unconfirmed), px-font-size, fixed-width, tap-target, image-ratio, repeated-structure, component-drift, loop-items, structure-scope, structure-names, component-block, component-tokens, invented-utility, inline-style, and for Etch etch-selectors, etch-atrule-tags, etch-root-theme, etch-html-font-size, etch-id-selectors, etch-important, etch-bem-depth, etch-card-block, etch-card-link, etch-nested-has, etch-nested-keyframes, etch-svg-data-uri. INFO: open-client-facts (open markers), percent-column-math, stale-year, semicolons, radius-scale. A save is never refused.
18
+ LAW CHECK: every save returns designLaw (score 0 to 100, findings with code, severity and fix). BLOCK, clear slop or a sure Etch break to fix before anything is called ready: emoji-icon, placeholder-image, placeholder-copy, text-contrast, fluid-type (no fluid type at all), grain, hidden-reveal, etch-custom-media, etch-expression-quotes. WARN: fluid-space, token-density, off-token-color, radius-sprawl, generic-gradient, center-everything, border-and-shadow, nested-cards, side-tab, eyebrow-sprawl, buzzwords, form-controls, pure-black-white, broad-will-change, mask-without-size, custom-cursor, italic-serif-hero, banned-face, svg-scene, radial-glow, dark-section, equal-cards, section-spacing, same-entrance, reveal-form, marquee, endless-animation, linear-easing, layout-motion, global-motion-reset, image-loading, unsourced-claim (a claim the brief does not give: mark it [GAP: what is missing], or [UNVERIFIED: what] when stated but unconfirmed), px-font-size, fixed-width, tap-target, image-ratio, repeated-structure, component-drift, loop-items, structure-scope, structure-names, component-block, component-tokens, invented-utility, inline-style, template-bindings, archive-loop, every other etch-* code, and on ACSS sites the acss-* codes. INFO: open-client-facts (open markers), percent-column-math, stale-year, semicolons, radius-scale. A save is never refused.
17
19
 
18
20
  IMAGES YOU NEED: a photo or illustration nobody supplied is made, not hotlinked. generate_image (the workspace's own OpenAI or Google key) or add_image, poll get_image until ready, then place its placeableUrl with real alt text. get_wireframe_context lists the project's ready images under projectImages.
19
21
 
@@ -640,15 +642,19 @@ SpecShot builds a whole site in three stages, so every page shares one system an
640
642
 
641
643
  1. Read the plan. Call get_site_plan with the projectId. It returns the site map, the families, the site system, the open run and where each reference goes, and next, the one thing to do now. If a run of SpecShot's own generator is open, stop and say so: the site is being made in SpecShot.
642
644
 
643
- 2. The site system. With an approved kit, read it once with get_site_kit. With none, save one now with save_site_kit, or start the run (step 4), whose first item is the site system. Write one style guide: the site header and footer outside <main>, one <style> with the token :root, and every part marked with data-component and data-prop (the item's parts list names them). Take the faces from the TYPE FACTS, never a default face. Fix every block finding in kitFindings, designLaw and layoutCheck, and save again.
645
+ CONTENT MODEL FIRST. Read the site structure with get_site_structure: which pages stay unique Pages, and which are a content type's archive (the list of all items), single (the design every item uses), category pages and items. Two or more pages that do one job (docs, a blog, a changelog, legal pages, services, features) are a type, never plain Pages, and Etch's own post types come first with ACF suggested when the project needs it. Propose corrections with set_site_structure; a person confirms the structure in SpecShot (Build, then Structure). Every whole-site build and deploy is refused while the structure is unconfirmed or a block finding of the structure check stands, with the sentence and the fix. Load the content-model skill with get_skill.
646
+
647
+ 2. The site system. With an approved kit, read it once with get_site_kit and detail: "full", so every component's definition is whole. With none, save one now with save_site_kit, or start the run (step 4), whose first item is the site system. Write one style guide: the site header and footer outside <main>, one <style> with the token :root, and every part marked with data-component and data-prop (the item's parts list names them). Take the faces from the TYPE FACTS, never a default face. Fix every block finding in kitFindings, designLaw and layoutCheck, and save again.
644
648
 
645
- 3. The families. Call set_page_families with groupByCode: true to group the pages by their addresses. Then give each family its job, its hero archetype (no two families share one), its signature interaction, its section plan (no two adjacent sections share a layout, and a section a page may leave out is marked optional) and its kit components, and pick its pilot: the page with the most real material. A change that adds an error to the plan is refused with its findings, and nothing is written.
649
+ 3. The families. Call set_page_families with groupByCode: true to group the pages by their addresses. Then give each family its job, its hero idea (no two families share one), its signature interaction, its section plan (the jobs a page of the family does, each with a key, a name, its purpose and the material it needs, a layout that fits as one option, and optional where a page may leave it out) and its kit components, and pick its pilot: the page with the most real material. The plan says what the pages cover, never how: every page composes its own. A change that adds an error to the plan is refused with its findings, and nothing is written.
646
650
 
647
- 4. Start. Call next_site_page with start: true. It starts an agent-driven run of every page that is not approved yet. Approved pages are never touched.
651
+ 4. Start. Call next_site_page with start: true. It starts an agent-driven run of every page that is not approved yet. Approved pages are never touched, unless the owner asks for them again: start: true with their pageIds and redesign: true makes each as a new design that is approved again.
648
652
 
649
653
  5. The loop. Call next_site_page and do what its item asks.
650
654
  - The site system item: write the style guide and save it with save_site_kit and the itemId.
651
- - A pilot or a page: read the blocks in order (the site brief with the client's rules first, the kit, the family template, the skills, the TYPE FACTS, then the page's own facts and copy), and open the image references. Then write only mainHtml and pageCss and publish them with publish_page_version, sending projectId, itemId, mainHtml, pageCss and the sections the item names. SpecShot composes the page from the kit and checks it.
655
+ - A pilot or a page: read the blocks in order (the site brief with the client's rules first, the kit, the family block, the skills, the TYPE FACTS, then the page's own facts and copy), and open the image references. Then write only mainHtml and pageCss and publish them with publish_page_version, sending projectId, itemId, mainHtml, pageCss and the sections the item names. SpecShot composes the page from the kit and checks it.
656
+ - Every page keeps the kit's parts and its type's bindings and chooses its own composition: never copy the pilot's sections, their order or their layouts. A type's single design marks data-bind="title", data-bind="field:<key>" and data-bind="content" on the body; its archive puts data-loop="main" on its list with one card. The law check warns template-bindings and archive-loop when they are missing.
657
+ - A Copy button on a command or config carries data-ss-copy, and a contact form is <form data-ss-form="contact"> with fields name, email and message, one submit button and no action: the SpecShot plugin makes both work.
652
658
  - Read the findings. A first publish with a block finding stays yours for one fix: correct exactly those findings and publish again with the same itemId. That publish finishes the page, flagged if a block finding is left.
653
659
  - Pass known with the fingerprints of the blocks you already hold, so a family's later pages send only their own words.
654
660
 
@@ -1751,8 +1757,8 @@ components or loops yet, the same build lands as plain blocks and says so.
1751
1757
  The marks:
1752
1758
 
1753
1759
  - \`data-component="PricingTier"\` on each instance's root (PascalCase).
1754
- - \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"\` or
1755
- \`"boolean"\` with \`data-prop-class="pricing-tier--featured"\`.
1760
+ - \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"\`,
1761
+ \`"boolean"\` with \`data-prop-class\`, or \`"attr"\` with \`data-prop-attr="placeholder"\`.
1756
1762
  - \`data-slot="actions"\` on the element whose children differ per instance.
1757
1763
  - \`data-loop="tiers"\` on the container of the instances (or of one repeated structure).
1758
1764
  - \`data-optional\` on a prop element some instances leave empty or leave out.
@@ -1776,6 +1782,24 @@ The marks:
1776
1782
  </ul>
1777
1783
  \`\`\`
1778
1784
 
1785
+ ## Content model
1786
+
1787
+ 1. Model the content first. A page is a unique Page (home, about, pricing, contact) or part of a content type: two or more pages that do one job (docs, a blog, legal pages, services) are a type with an archive, a single, category pages and items, never plain Pages. Not found and search are site templates.
1788
+ Why: The owner, 2026-11-08. Etch builds every item of a type from one single template and lists them on one archive template (docs.etchwp.com /templates).
1789
+ A whole-site build stops on it.
1790
+
1791
+ 2. A type's single design marks data-bind="title", data-bind="field:<key>" on each value the items share (also excerpt, date, image and url), and data-bind="content" on the element that holds the item's own body.
1792
+ Why: Etch reads them as {this.title}, the type's fields and Post Content; unmarked, every item shows the sample words.
1793
+ Checked at save as \`template-bindings\`.
1794
+
1795
+ 3. A type's archive, category or search design puts data-loop="main" on its list with ONE card whose props are post fields.
1796
+ Why: It becomes Etch's Main Query loop over the real items, with pagination (docs.etchwp.com /loops/main-query). A JSON copy never changes when a post is added.
1797
+ Checked at save as \`archive-loop\`.
1798
+
1799
+ 4. Etch's own post types and fields first; ACF is suggested, with the reason, for images, dates, relationships or repeaters. ACF creates categories for you; Etch's own are made by hand for now.
1800
+ Why: The owner, 2026-11-08. Etch documents only text, textarea, number and yes or no fields, and calls its own types a proof of concept.
1801
+ Nobody checks this but you.
1802
+
1779
1803
  ## Components
1780
1804
 
1781
1805
  1. Make a component of anything that repeats twice or more on a page, or that the site uses across pages: cards, pricing tiers, team members, FAQ items, testimonials, feature rows, nav items, buttons. Mark its root with data-component and a PascalCase name (data-component="PricingTier"). Every instance with that name has the same structure, and the first one is the definition.
@@ -1812,8 +1836,8 @@ The marks:
1812
1836
 
1813
1837
  ## Logic
1814
1838
 
1815
- 1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
1816
- Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so the agency adds a fourth tier by adding one item, not by duplicating blocks.
1839
+ 1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks, which may hold components with their own values (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
1840
+ Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so a fourth tier is one more item.
1817
1841
  Checked at save as \`loop-items\`.
1818
1842
 
1819
1843
  2. An optional part is a condition (data-optional), never a second copy of the block without it. No copy-pasted near-identical blocks anywhere on the page: make them one component with a variant, or one loop.
@@ -1852,8 +1876,8 @@ The marks:
1852
1876
  Why: The export nests .faq-item.is-open inside the block's Etch style as &.is-open, so the state sits beside the block in the style manager, and any script or Etch interaction toggles the same class.
1853
1877
  Nobody checks this but you.
1854
1878
 
1855
- 3. Utility classes only from the site's Automatic.css when the site runs it (pad--m, text--l, grid--3), and none of your own: never define .mt-4, .flex, .text-center, or a copy of an ACSS utility. Style a block's element with its own BEM class instead.
1856
- Why: An invented utility is a second design system inside the page that nobody maintains. On an ACSS site the real utilities already exist and follow the site's settings.
1879
+ 3. No utility classes of your own (.mt-4, .flex, .text-center, a copy of an ACSS utility): style an element with its own BEM class. On an ACSS 4 site use only the classes it still ships (btn--primary, section--l, text--m) and its variables in your class (var(--grid-3)); its 3.x utilities (grid--3, pad--m) are gone.
1880
+ Why: An invented utility is a second design system nobody maintains, and ACSS 4 removed most of its own utilities (docs.automaticcss.com /setup/working-in-acss-4).
1857
1881
  Checked at save as \`invented-utility\`.
1858
1882
 
1859
1883
  4. No inline style attributes. The one exception is a custom property that carries data (style="--i: 2" for a stagger index).
@@ -1870,7 +1894,7 @@ The marks:
1870
1894
  Why: A component that reads roles follows the brand and the theme from one place, and its own token is the one dial the agency turns for that component alone.
1871
1895
  Nobody checks this but you.
1872
1896
 
1873
- 2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m, 14px). No raw hex, rgb, oklch, px or rem where a token exists.
1897
+ 2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m, 1rem). No raw hex, rgb, oklch, px or rem where a token exists.
1874
1898
  Why: A raw value inside a component is the one place a rebrand or an ACSS retune never reaches, and every instance carries it.
1875
1899
  Checked at save as \`component-tokens\`.
1876
1900
 
@@ -1899,19 +1923,19 @@ edit in Etch rather than one they have to rebuild.
1899
1923
  Checked at save as \`etch-selectors\`.
1900
1924
 
1901
1925
  2. Inside @supports, @container and @layer, select by class only. No tag, universal or attribute-led selectors there.
1902
- Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's wrapper on export, but a design that is only safe because the exporter rescued it is a design that breaks in any other builder.
1926
+ Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's sections on export, but a design that is only safe because the exporter rescued it is a design that breaks in any other builder.
1903
1927
  Checked at save as \`etch-atrule-tags\`.
1904
1928
 
1905
1929
  3. Name every @keyframes for its block: hero-settle, chart-grow, faq-open. Never fadeIn, rise, spin or float.
1906
1930
  Why: Keyframe names are global on the site. A design's fadeIn replaces the theme's fadeIn, or is replaced by it. SpecShot also prefixes keyframes with the project's prefix on export.
1907
1931
  Checked at save as \`etch-keyframes\`.
1908
1932
 
1909
- 4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the design's own root wrapper (.page--dark). Never :root[data-theme=dark] or html[data-theme=dark].
1910
- Why: In Etch the design is one block inside the client's page, and :root and html belong to the site. A :root[data-theme] selector never matches the design there. The exporter maps it to the wrapper with the same attribute, which keeps it working only where someone sets that attribute on the block.
1933
+ 4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the section it changes (.cta-band--night). Never :root[data-theme=dark] or html[data-theme=dark].
1934
+ Why: In Etch the design's sections sit inside the client's page, and :root and html belong to the site, so a :root[data-theme] selector never matches there. The exporter carries the attribute onto each top-level section, which works only where they hold it.
1911
1935
  Checked at save as \`etch-root-theme\`.
1912
1936
 
1913
1937
  5. Never set font-size on html or :root. Size type with the --step tokens.
1914
- Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's wrapper, where font-size no longer drives rem, so a design that changed the root size renders at a different scale on the site.
1938
+ Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's sections, where font-size no longer drives rem, so a design that changed the root size renders at a different scale on the site.
1915
1939
  Checked at save as \`etch-html-font-size\`.
1916
1940
 
1917
1941
  6. Style with classes only: no #id selectors, and no !important outside a prefers-reduced-motion block.
@@ -1925,8 +1949,8 @@ edit in Etch rather than one they have to rebuild.
1925
1949
  Why: A placeable image becomes an asset in the Etch build: a temporary link that the agency uploads to the site's media library, after which the build binds it as a responsive Etch image. A hotlink renders as a gray box in the preview and a broken image on the site.
1926
1950
  Checked at save as \`placeholder-image\`.
1927
1951
 
1928
- 9. One page, one root: body holds the header, main and footer and nothing is positioned against html or body.
1929
- Why: The body becomes the one root block, labeled SpecShot: <name> [id] in Etch's structure panel. Running the build again replaces exactly that block and nothing else on the page.
1952
+ 9. Sections at the top: body holds the header, main and footer; main holds the sections side by side, never nested or wrapped, each with one container. Nothing is positioned against html or body. In a whole-site build the header and footer are kit components.
1953
+ Why: Each section becomes its own top-level block in Etch, Etch's own Section and Container, where Automatic.css sets spacing, gutter and width. A rebuild replaces only those.
1930
1954
 
1931
1955
  10. Embed the faces in the design (get_font_faces) so the preview renders them; know that the site installs them separately.
1932
1956
  Why: Embedded data: fonts are left out of the Etch build and named in its warnings, so the agency installs the same families on the site. A face the design names but never embeds renders in a fallback everywhere.
@@ -2124,7 +2148,12 @@ any of them; the score is how a revision is seen to move.
2124
2148
  - :has() inside :has(), checked by law check \`etch-nested-has\` [WARN].
2125
2149
  - @keyframes inside a rule, checked by law check \`etch-nested-keyframes\` [WARN].
2126
2150
  - Raw SVG markup in a CSS data URI, checked by law check \`etch-svg-data-uri\` [WARN].
2127
- - A double quote inside an Etch expression, checked by law check \`etch-expression-quotes\` [BLOCK].`,
2151
+ - A double quote inside an Etch expression, checked by law check \`etch-expression-quotes\` [BLOCK].
2152
+ - A type's single design with no data-bind="title", checked by law check \`template-bindings\` [WARN].
2153
+ - A type's archive design with no data-loop="main", checked by law check \`archive-loop\` [WARN].
2154
+ - On an ACSS site, a class or token ACSS 4 removed or already ships (grid--3, --primary-trans-50, a hidden-text class), checked by law check \`acss-classes\` [WARN].
2155
+ - On an ACSS site, a section with no single inner wrapper, checked by law check \`acss-sections\` [WARN].
2156
+ - On an ACSS site, dark mode that fixes ACSS's color tokens to literal values, checked by law check \`acss-color-scheme\` [WARN].`,
2128
2157
  },
2129
2158
  {
2130
2159
  name: "premium_craft",
@@ -2536,19 +2565,19 @@ edit in Etch rather than one they have to rebuild.
2536
2565
  Checked at save as \`etch-selectors\`.
2537
2566
 
2538
2567
  2. Inside @supports, @container and @layer, select by class only. No tag, universal or attribute-led selectors there.
2539
- Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's wrapper on export, but a design that is only safe because the exporter rescued it is a design that breaks in any other builder.
2568
+ Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's sections on export, but a design that is only safe because the exporter rescued it is a design that breaks in any other builder.
2540
2569
  Checked at save as \`etch-atrule-tags\`.
2541
2570
 
2542
2571
  3. Name every @keyframes for its block: hero-settle, chart-grow, faq-open. Never fadeIn, rise, spin or float.
2543
2572
  Why: Keyframe names are global on the site. A design's fadeIn replaces the theme's fadeIn, or is replaced by it. SpecShot also prefixes keyframes with the project's prefix on export.
2544
2573
  Checked at save as \`etch-keyframes\`.
2545
2574
 
2546
- 4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the design's own root wrapper (.page--dark). Never :root[data-theme=dark] or html[data-theme=dark].
2547
- Why: In Etch the design is one block inside the client's page, and :root and html belong to the site. A :root[data-theme] selector never matches the design there. The exporter maps it to the wrapper with the same attribute, which keeps it working only where someone sets that attribute on the block.
2575
+ 4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the section it changes (.cta-band--night). Never :root[data-theme=dark] or html[data-theme=dark].
2576
+ Why: In Etch the design's sections sit inside the client's page, and :root and html belong to the site, so a :root[data-theme] selector never matches there. The exporter carries the attribute onto each top-level section, which works only where they hold it.
2548
2577
  Checked at save as \`etch-root-theme\`.
2549
2578
 
2550
2579
  5. Never set font-size on html or :root. Size type with the --step tokens.
2551
- Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's wrapper, where font-size no longer drives rem, so a design that changed the root size renders at a different scale on the site.
2580
+ Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's sections, where font-size no longer drives rem, so a design that changed the root size renders at a different scale on the site.
2552
2581
  Checked at save as \`etch-html-font-size\`.
2553
2582
 
2554
2583
  6. Style with classes only: no #id selectors, and no !important outside a prefers-reduced-motion block.
@@ -2562,8 +2591,8 @@ edit in Etch rather than one they have to rebuild.
2562
2591
  Why: A placeable image becomes an asset in the Etch build: a temporary link that the agency uploads to the site's media library, after which the build binds it as a responsive Etch image. A hotlink renders as a gray box in the preview and a broken image on the site.
2563
2592
  Checked at save as \`placeholder-image\`.
2564
2593
 
2565
- 9. One page, one root: body holds the header, main and footer and nothing is positioned against html or body.
2566
- Why: The body becomes the one root block, labeled SpecShot: <name> [id] in Etch's structure panel. Running the build again replaces exactly that block and nothing else on the page.
2594
+ 9. Sections at the top: body holds the header, main and footer; main holds the sections side by side, never nested or wrapped, each with one container. Nothing is positioned against html or body. In a whole-site build the header and footer are kit components.
2595
+ Why: Each section becomes its own top-level block in Etch, Etch's own Section and Container, where Automatic.css sets spacing, gutter and width. A rebuild replaces only those.
2567
2596
 
2568
2597
  10. Embed the faces in the design (get_font_faces) so the preview renders them; know that the site installs them separately.
2569
2598
  Why: Embedded data: fonts are left out of the Etch build and named in its warnings, so the agency installs the same families on the site. A face the design names but never embeds renders in a fallback everywhere.
@@ -2633,8 +2662,8 @@ components or loops yet, the same build lands as plain blocks and says so.
2633
2662
  The marks:
2634
2663
 
2635
2664
  - \`data-component="PricingTier"\` on each instance's root (PascalCase).
2636
- - \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"\` or
2637
- \`"boolean"\` with \`data-prop-class="pricing-tier--featured"\`.
2665
+ - \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"\`,
2666
+ \`"boolean"\` with \`data-prop-class\`, or \`"attr"\` with \`data-prop-attr="placeholder"\`.
2638
2667
  - \`data-slot="actions"\` on the element whose children differ per instance.
2639
2668
  - \`data-loop="tiers"\` on the container of the instances (or of one repeated structure).
2640
2669
  - \`data-optional\` on a prop element some instances leave empty or leave out.
@@ -2658,6 +2687,24 @@ The marks:
2658
2687
  </ul>
2659
2688
  \`\`\`
2660
2689
 
2690
+ ## Content model
2691
+
2692
+ 1. Model the content first. A page is a unique Page (home, about, pricing, contact) or part of a content type: two or more pages that do one job (docs, a blog, legal pages, services) are a type with an archive, a single, category pages and items, never plain Pages. Not found and search are site templates.
2693
+ Why: The owner, 2026-11-08. Etch builds every item of a type from one single template and lists them on one archive template (docs.etchwp.com /templates).
2694
+ A whole-site build stops on it.
2695
+
2696
+ 2. A type's single design marks data-bind="title", data-bind="field:<key>" on each value the items share (also excerpt, date, image and url), and data-bind="content" on the element that holds the item's own body.
2697
+ Why: Etch reads them as {this.title}, the type's fields and Post Content; unmarked, every item shows the sample words.
2698
+ Checked at save as \`template-bindings\`.
2699
+
2700
+ 3. A type's archive, category or search design puts data-loop="main" on its list with ONE card whose props are post fields.
2701
+ Why: It becomes Etch's Main Query loop over the real items, with pagination (docs.etchwp.com /loops/main-query). A JSON copy never changes when a post is added.
2702
+ Checked at save as \`archive-loop\`.
2703
+
2704
+ 4. Etch's own post types and fields first; ACF is suggested, with the reason, for images, dates, relationships or repeaters. ACF creates categories for you; Etch's own are made by hand for now.
2705
+ Why: The owner, 2026-11-08. Etch documents only text, textarea, number and yes or no fields, and calls its own types a proof of concept.
2706
+ Nobody checks this but you.
2707
+
2661
2708
  ## Components
2662
2709
 
2663
2710
  1. Make a component of anything that repeats twice or more on a page, or that the site uses across pages: cards, pricing tiers, team members, FAQ items, testimonials, feature rows, nav items, buttons. Mark its root with data-component and a PascalCase name (data-component="PricingTier"). Every instance with that name has the same structure, and the first one is the definition.
@@ -2694,8 +2741,8 @@ The marks:
2694
2741
 
2695
2742
  ## Logic
2696
2743
 
2697
- 1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
2698
- Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so the agency adds a fourth tier by adding one item, not by duplicating blocks.
2744
+ 1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks, which may hold components with their own values (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
2745
+ Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so a fourth tier is one more item.
2699
2746
  Checked at save as \`loop-items\`.
2700
2747
 
2701
2748
  2. An optional part is a condition (data-optional), never a second copy of the block without it. No copy-pasted near-identical blocks anywhere on the page: make them one component with a variant, or one loop.
@@ -2734,8 +2781,8 @@ The marks:
2734
2781
  Why: The export nests .faq-item.is-open inside the block's Etch style as &.is-open, so the state sits beside the block in the style manager, and any script or Etch interaction toggles the same class.
2735
2782
  Nobody checks this but you.
2736
2783
 
2737
- 3. Utility classes only from the site's Automatic.css when the site runs it (pad--m, text--l, grid--3), and none of your own: never define .mt-4, .flex, .text-center, or a copy of an ACSS utility. Style a block's element with its own BEM class instead.
2738
- Why: An invented utility is a second design system inside the page that nobody maintains. On an ACSS site the real utilities already exist and follow the site's settings.
2784
+ 3. No utility classes of your own (.mt-4, .flex, .text-center, a copy of an ACSS utility): style an element with its own BEM class. On an ACSS 4 site use only the classes it still ships (btn--primary, section--l, text--m) and its variables in your class (var(--grid-3)); its 3.x utilities (grid--3, pad--m) are gone.
2785
+ Why: An invented utility is a second design system nobody maintains, and ACSS 4 removed most of its own utilities (docs.automaticcss.com /setup/working-in-acss-4).
2739
2786
  Checked at save as \`invented-utility\`.
2740
2787
 
2741
2788
  4. No inline style attributes. The one exception is a custom property that carries data (style="--i: 2" for a stagger index).
@@ -2752,7 +2799,7 @@ The marks:
2752
2799
  Why: A component that reads roles follows the brand and the theme from one place, and its own token is the one dial the agency turns for that component alone.
2753
2800
  Nobody checks this but you.
2754
2801
 
2755
- 2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m, 14px). No raw hex, rgb, oklch, px or rem where a token exists.
2802
+ 2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m, 1rem). No raw hex, rgb, oklch, px or rem where a token exists.
2756
2803
  Why: A raw value inside a component is the one place a rebrand or an ACSS retune never reaches, and every instance carries it.
2757
2804
  Checked at save as \`component-tokens\`.
2758
2805
 
@@ -3448,21 +3495,28 @@ Never: Copying the reference. Take only its structure and layout. Never reuse it
3448
3495
 
3449
3496
  Say "rebuilt from" or "used as a reference". Never "cloned" or "copied".
3450
3497
 
3498
+ ## When the task says Match the capture's look is on
3499
+
3500
+ The owner asked for the capture's exact look, or the capture is the client's own website. For that task only, you may match the capture's exact colors and fonts, which replaces those two limits in the boundary above and in step 6 below. The words never come from the capture, even then: every client gets words written for them, so write every word new for this project as step 4 says, and read the capture's text only for the length, tone and hierarchy to aim for. get_wireframe_context and get_capture then give you the whole capture, with a matchLook note on it. save_wireframe still holds six or more of its words in a row, one of its headings and an image from its site as block findings, and reports its colors, faces and class names in the originality line instead. Its images, logos and icons still come from the project, and everything else below stands.
3501
+
3502
+ REBUILT FROM A CAPTURE, also checked on every save:
3503
+ - In a section rebuilt from a capture, anything of the reference's but its structure and layout: six or more of its words in a row or one of its headings, an image from its site, a brand color or a face of its that the project's brand does not share, or one of its own class names. SpecShot reads the capture on the server and checks the rebuild against it, checked by law check \`originality\` [BLOCK].
3504
+
3451
3505
  ## The steps
3452
3506
 
3453
3507
  1. READ THE TASK. Call get_agent_tasks with the projectId and status "queued". The rebuild task's description names the capture id, the exact name to save under, the page it is for (if any) and the owner's note. Set it to "running" with update_agent_task, so the owner sees you have it.
3454
3508
 
3455
- 2. READ THE PROJECT. Call get_wireframe_context with the projectId. When its BRIEF opens with CLIENT RULES, those are the client's and the agency's own instructions: what is off-limits, what they may not legally say, how the site should come across, the brand assets they have. They apply to this section too, and they beat every default here, but never the boundary above. Find the capture by its id under captures and read its imageUrl (open it if you can see images), visualSummary, layout and motion. Note the brand tokens, the copyBlocks, the projectImages and etch.prefix (the prefix every token you declare carries in Etch). If the task names a page, read that page's goal in the page list. get_brand_system has the whole brand when you need more of it.
3509
+ 2. READ THE PROJECT. Call get_wireframe_context with the projectId. When its BRIEF opens with CLIENT RULES, those are the client's and the agency's own instructions: what is off-limits, what they may not legally say, how the site should come across, the brand assets they have. They apply to this section too, and they beat every default here, but never the boundary above. Find the capture by its id under captures. While this task is open it carries only what a rebuild may take from it, the same reference SpecShot's own generator gets: its imageUrl (a screenshot to look at if you can see images, never to place), its sectionType and its layout's shape. Do not go looking for more: get_capture answers with the same reference, and the capture's text, colors, faces, styles and markup are not yours to use. Note the brand tokens, the copyBlocks, the projectImages and etch.prefix (the prefix every token you declare carries in Etch). If the task names a page, read that page's goal in the page list. get_brand_system has the whole brand when you need more of it.
3456
3510
 
3457
- 3. STUDY THE REFERENCE FOR STRUCTURE ONLY. Before any markup, write down: how many columns, the order of the parts, what is grouped with what, which part dominates, the alignment, the density, and how it moves. Ignore its words, its colors, its pictures and its logo.
3511
+ 3. STUDY THE REFERENCE FOR STRUCTURE ONLY. Before any markup, write down: how many columns, the order of the parts, what is grouped with what, which part dominates, the alignment and the density. Ignore its words, its colors, its type, its pictures and its logo.
3458
3512
 
3459
3513
  4. WRITE THE COPY FOR THIS PROJECT. Use an approved copy block word for word where one fits, prefer a draft block over anything you would invent, and otherwise write plain, specific copy for this project. Real, uneven numbers. Never lorem, never buzzwords, never a word of the reference's text, and never a claim the CLIENT RULES put off-limits.
3460
3514
 
3461
3515
  5. IMAGERY. Use a project image (projectImages, or list_images) by its placeableUrl, or make one with generate_image (it runs on the workspace's own key; poll get_image until it is ready, then use its placeableUrl with real alt text). Draw icons as inline SVG. Never a placeholder image host, and never the capture's screenshot.
3462
3516
 
3463
- 6. BUILD ONE SECTION UNDER THE LAW. One <section> root carrying one BEM block class named for what it is (class="pricing"), single-class BEM selectors throughout, and one <style> block with the token :root at its top: every type and space step a clamp() with a literal fallback, under the token contract's names. Theme on the section's own root (never :root[data-theme] or html), no html font size, no ids, no !important, keyframes named for the block, no emoji as icons, and every state (hover, focus, active, disabled). Embed the faces with get_font_faces. No header, navigation, footer or main around it: the page it joins already has them.
3517
+ 6. BUILD ONE SECTION UNDER THE LAW. One <section> root carrying one BEM block class named for what it is (class="pricing"), single-class BEM selectors throughout, and one <style> block with the token :root at its top: every type and space step a clamp() with a literal fallback, under the token contract's names. Theme on the section's own root (never :root[data-theme] or html), no html font size, no ids, no !important, keyframes named for the block, no emoji as icons, and every state (hover, focus, active, disabled). The faces are the project's: the ones the brand names (get_brand_system), else the approved site kit's; with neither, choose a Google Fonts pairing for this project, never a banned default and never a face from the reference, and tell the owner the brand names no font. Embed them with get_font_faces. Every color comes from the brand's tokens. No header, navigation, footer or main around it: the page it joins already has them.
3464
3518
 
3465
- 7. SAVE IT AS A SECTION. Call save_wireframe with the projectId, the exact name from the task (for example "Pricing section, rebuilt from linear.app"), the html, pageType "section" and sections set to the section's one name, and NO pageSlug or pageId. A section filed under a page would stand in for that page's design. Do not use publish_page_version for it. Read designLaw in the response and revise_wireframe (with baseVersion) until it has no block findings.
3519
+ 7. SAVE IT AS A SECTION. Call save_wireframe with the projectId, the exact name from the task (for example "Pricing section, rebuilt from linear.app"), the html, pageType "section" and sections set to the section's one name, and NO pageSlug or pageId. A section filed under a page would stand in for that page's design. Do not use publish_page_version for it. SpecShot holds every save of it against the capture, on the server: six or more of its words in a row, one of its headings, an image from its site, one of its brand colors or faces, or one of its class names is a block finding under the code originality, and the response's originality line says what it found. Read designLaw in the response and revise_wireframe (with baseVersion) until it has no block findings.
3466
3520
 
3467
3521
  8. CLOSE THE TASK. Call update_agent_task with status "completed" and an outputSummary naming the design and its id.
3468
3522
 
@@ -4569,8 +4623,8 @@ components or loops yet, the same build lands as plain blocks and says so.
4569
4623
  The marks:
4570
4624
 
4571
4625
  - \`data-component="PricingTier"\` on each instance's root (PascalCase).
4572
- - \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"\` or
4573
- \`"boolean"\` with \`data-prop-class="pricing-tier--featured"\`.
4626
+ - \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"\`,
4627
+ \`"boolean"\` with \`data-prop-class\`, or \`"attr"\` with \`data-prop-attr="placeholder"\`.
4574
4628
  - \`data-slot="actions"\` on the element whose children differ per instance.
4575
4629
  - \`data-loop="tiers"\` on the container of the instances (or of one repeated structure).
4576
4630
  - \`data-optional\` on a prop element some instances leave empty or leave out.
@@ -4594,6 +4648,24 @@ The marks:
4594
4648
  </ul>
4595
4649
  \`\`\`
4596
4650
 
4651
+ ## Content model
4652
+
4653
+ 1. Model the content first. A page is a unique Page (home, about, pricing, contact) or part of a content type: two or more pages that do one job (docs, a blog, legal pages, services) are a type with an archive, a single, category pages and items, never plain Pages. Not found and search are site templates.
4654
+ Why: The owner, 2026-11-08. Etch builds every item of a type from one single template and lists them on one archive template (docs.etchwp.com /templates).
4655
+ A whole-site build stops on it.
4656
+
4657
+ 2. A type's single design marks data-bind="title", data-bind="field:<key>" on each value the items share (also excerpt, date, image and url), and data-bind="content" on the element that holds the item's own body.
4658
+ Why: Etch reads them as {this.title}, the type's fields and Post Content; unmarked, every item shows the sample words.
4659
+ Checked at save as \`template-bindings\`.
4660
+
4661
+ 3. A type's archive, category or search design puts data-loop="main" on its list with ONE card whose props are post fields.
4662
+ Why: It becomes Etch's Main Query loop over the real items, with pagination (docs.etchwp.com /loops/main-query). A JSON copy never changes when a post is added.
4663
+ Checked at save as \`archive-loop\`.
4664
+
4665
+ 4. Etch's own post types and fields first; ACF is suggested, with the reason, for images, dates, relationships or repeaters. ACF creates categories for you; Etch's own are made by hand for now.
4666
+ Why: The owner, 2026-11-08. Etch documents only text, textarea, number and yes or no fields, and calls its own types a proof of concept.
4667
+ Nobody checks this but you.
4668
+
4597
4669
  ## Components
4598
4670
 
4599
4671
  1. Make a component of anything that repeats twice or more on a page, or that the site uses across pages: cards, pricing tiers, team members, FAQ items, testimonials, feature rows, nav items, buttons. Mark its root with data-component and a PascalCase name (data-component="PricingTier"). Every instance with that name has the same structure, and the first one is the definition.
@@ -4630,8 +4702,8 @@ The marks:
4630
4702
 
4631
4703
  ## Logic
4632
4704
 
4633
- 1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
4634
- Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so the agency adds a fourth tier by adding one item, not by duplicating blocks.
4705
+ 1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks, which may hold components with their own values (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
4706
+ Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so a fourth tier is one more item.
4635
4707
  Checked at save as \`loop-items\`.
4636
4708
 
4637
4709
  2. An optional part is a condition (data-optional), never a second copy of the block without it. No copy-pasted near-identical blocks anywhere on the page: make them one component with a variant, or one loop.
@@ -4670,8 +4742,8 @@ The marks:
4670
4742
  Why: The export nests .faq-item.is-open inside the block's Etch style as &.is-open, so the state sits beside the block in the style manager, and any script or Etch interaction toggles the same class.
4671
4743
  Nobody checks this but you.
4672
4744
 
4673
- 3. Utility classes only from the site's Automatic.css when the site runs it (pad--m, text--l, grid--3), and none of your own: never define .mt-4, .flex, .text-center, or a copy of an ACSS utility. Style a block's element with its own BEM class instead.
4674
- Why: An invented utility is a second design system inside the page that nobody maintains. On an ACSS site the real utilities already exist and follow the site's settings.
4745
+ 3. No utility classes of your own (.mt-4, .flex, .text-center, a copy of an ACSS utility): style an element with its own BEM class. On an ACSS 4 site use only the classes it still ships (btn--primary, section--l, text--m) and its variables in your class (var(--grid-3)); its 3.x utilities (grid--3, pad--m) are gone.
4746
+ Why: An invented utility is a second design system nobody maintains, and ACSS 4 removed most of its own utilities (docs.automaticcss.com /setup/working-in-acss-4).
4675
4747
  Checked at save as \`invented-utility\`.
4676
4748
 
4677
4749
  4. No inline style attributes. The one exception is a custom property that carries data (style="--i: 2" for a stagger index).
@@ -4688,7 +4760,7 @@ The marks:
4688
4760
  Why: A component that reads roles follows the brand and the theme from one place, and its own token is the one dial the agency turns for that component alone.
4689
4761
  Nobody checks this but you.
4690
4762
 
4691
- 2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m, 14px). No raw hex, rgb, oklch, px or rem where a token exists.
4763
+ 2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m, 1rem). No raw hex, rgb, oklch, px or rem where a token exists.
4692
4764
  Why: A raw value inside a component is the one place a rebrand or an ACSS retune never reaches, and every instance carries it.
4693
4765
  Checked at save as \`component-tokens\`.
4694
4766
 
@@ -4717,19 +4789,19 @@ edit in Etch rather than one they have to rebuild.
4717
4789
  Checked at save as \`etch-selectors\`.
4718
4790
 
4719
4791
  2. Inside @supports, @container and @layer, select by class only. No tag, universal or attribute-led selectors there.
4720
- Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's wrapper on export, but a design that is only safe because the exporter rescued it is a design that breaks in any other builder.
4792
+ Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's sections on export, but a design that is only safe because the exporter rescued it is a design that breaks in any other builder.
4721
4793
  Checked at save as \`etch-atrule-tags\`.
4722
4794
 
4723
4795
  3. Name every @keyframes for its block: hero-settle, chart-grow, faq-open. Never fadeIn, rise, spin or float.
4724
4796
  Why: Keyframe names are global on the site. A design's fadeIn replaces the theme's fadeIn, or is replaced by it. SpecShot also prefixes keyframes with the project's prefix on export.
4725
4797
  Checked at save as \`etch-keyframes\`.
4726
4798
 
4727
- 4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the design's own root wrapper (.page--dark). Never :root[data-theme=dark] or html[data-theme=dark].
4728
- Why: In Etch the design is one block inside the client's page, and :root and html belong to the site. A :root[data-theme] selector never matches the design there. The exporter maps it to the wrapper with the same attribute, which keeps it working only where someone sets that attribute on the block.
4799
+ 4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the section it changes (.cta-band--night). Never :root[data-theme=dark] or html[data-theme=dark].
4800
+ Why: In Etch the design's sections sit inside the client's page, and :root and html belong to the site, so a :root[data-theme] selector never matches there. The exporter carries the attribute onto each top-level section, which works only where they hold it.
4729
4801
  Checked at save as \`etch-root-theme\`.
4730
4802
 
4731
4803
  5. Never set font-size on html or :root. Size type with the --step tokens.
4732
- Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's wrapper, where font-size no longer drives rem, so a design that changed the root size renders at a different scale on the site.
4804
+ Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's sections, where font-size no longer drives rem, so a design that changed the root size renders at a different scale on the site.
4733
4805
  Checked at save as \`etch-html-font-size\`.
4734
4806
 
4735
4807
  6. Style with classes only: no #id selectors, and no !important outside a prefers-reduced-motion block.
@@ -4743,8 +4815,8 @@ edit in Etch rather than one they have to rebuild.
4743
4815
  Why: A placeable image becomes an asset in the Etch build: a temporary link that the agency uploads to the site's media library, after which the build binds it as a responsive Etch image. A hotlink renders as a gray box in the preview and a broken image on the site.
4744
4816
  Checked at save as \`placeholder-image\`.
4745
4817
 
4746
- 9. One page, one root: body holds the header, main and footer and nothing is positioned against html or body.
4747
- Why: The body becomes the one root block, labeled SpecShot: <name> [id] in Etch's structure panel. Running the build again replaces exactly that block and nothing else on the page.
4818
+ 9. Sections at the top: body holds the header, main and footer; main holds the sections side by side, never nested or wrapped, each with one container. Nothing is positioned against html or body. In a whole-site build the header and footer are kit components.
4819
+ Why: Each section becomes its own top-level block in Etch, Etch's own Section and Container, where Automatic.css sets spacing, gutter and width. A rebuild replaces only those.
4748
4820
 
4749
4821
  10. Embed the faces in the design (get_font_faces) so the preview renders them; know that the site installs them separately.
4750
4822
  Why: Embedded data: fonts are left out of the Etch build and named in its warnings, so the agency installs the same families on the site. A face the design names but never embeds renders in a fallback everywhere.
@@ -4942,7 +5014,12 @@ any of them; the score is how a revision is seen to move.
4942
5014
  - :has() inside :has(), checked by law check \`etch-nested-has\` [WARN].
4943
5015
  - @keyframes inside a rule, checked by law check \`etch-nested-keyframes\` [WARN].
4944
5016
  - Raw SVG markup in a CSS data URI, checked by law check \`etch-svg-data-uri\` [WARN].
4945
- - A double quote inside an Etch expression, checked by law check \`etch-expression-quotes\` [BLOCK].`,
5017
+ - A double quote inside an Etch expression, checked by law check \`etch-expression-quotes\` [BLOCK].
5018
+ - A type's single design with no data-bind="title", checked by law check \`template-bindings\` [WARN].
5019
+ - A type's archive design with no data-loop="main", checked by law check \`archive-loop\` [WARN].
5020
+ - On an ACSS site, a class or token ACSS 4 removed or already ships (grid--3, --primary-trans-50, a hidden-text class), checked by law check \`acss-classes\` [WARN].
5021
+ - On an ACSS site, a section with no single inner wrapper, checked by law check \`acss-sections\` [WARN].
5022
+ - On an ACSS site, dark mode that fixes ACSS's color tokens to literal values, checked by law check \`acss-color-scheme\` [WARN].`,
4946
5023
  },
4947
5024
  {
4948
5025
  name: "new_client",
@@ -4954,10 +5031,10 @@ The owner has a new client. Get what the owner knows about them into SpecShot, w
4954
5031
 
4955
5032
  Load the agency-process skill with get_skill first if you have not this session. It holds the phases, their gates, and the rule that a client fact nobody gave is a labeled gap, never an invented value.
4956
5033
 
4957
- 1. A person creates the client and its first project in SpecShot (New client under Clients, then New project); no tool creates them. Ask whether that is done, then find the project with list_projects and read it with get_project_state and get_project_intelligence.
5034
+ 1. Find the client with list_clients first, so it is never made twice. When it is not there and the owner asks you to add it, create it with create_client, sending only what the owner said: the name, and the website, notes and first contact only when given. Find its project with list_projects. When it has none yet and the owner asks for one, create it with create_project, linking the client by its clientFolderId and sending only what the owner said. Read the project with get_project_state and get_project_intelligence.
4958
5035
  2. Interview the owner one question at a time, by the new client part of the skill below. Push on vague answers, and stop when another question would only produce detail nobody needs.
4959
5036
  3. Write what the brief holds with set_project_intelligence as you go: answers as question and answer pairs under discovery, the platform in platformPreferences, hard limits and claims that need a document in constraints, choices already made in decisions, and every unknown in openQuestions. Mark a fact stated but unconfirmed [UNVERIFIED] and an unknown one [GAP].
4960
- 4. Contact names, titles and who approves what belong on the client's record in SpecShot, which a person edits under Clients: give the owner the lines to add.
5037
+ 4. Contact names, roles and who approves designs belong on the client's record. Read who is there with list_client_contacts, then add a person the owner named with add_client_contact, or correct one with update_client_contact, sending only what the owner said. When your token's seat may not make the change, give the owner the lines to add under Clients.
4961
5038
  5. Taste a person stated in their own words goes in with save_decision, saying who said it.
4962
5039
  6. Finish with how many gaps are open (a number) and the three or four that matter most. Never contact the client, never set a price and never touch a site.
4963
5040
 
@@ -4993,7 +5070,7 @@ How to run discovery as a conversation, and how the answers become the project's
4993
5070
 
4994
5071
  ## A new client
4995
5072
 
4996
- Before the first project of a new client, a person creates the client and the project in SpecShot (Clients, then Projects). Then interview the owner, one question at a time, and stop when another question would only produce detail nobody needs:
5073
+ Before the first project of a new client, the client and the project are in SpecShot: a person adds them (Clients, then Projects), or you add them when the owner asks (create_client after list_clients shows the client is not there yet, then create_project). Then interview the owner, one question at a time, and stop when another question would only produce detail nobody needs:
4997
5074
 
4998
5075
  - Who they are: what the business does, its customers, its size, where it is, its website.
4999
5076
  - The people: names, exact titles, who has final say, who handles the day to day, anyone outside the company involved.
@@ -5065,7 +5142,7 @@ How to run discovery as a conversation, and how the answers become the project's
5065
5142
 
5066
5143
  ## A new client
5067
5144
 
5068
- Before the first project of a new client, a person creates the client and the project in SpecShot (Clients, then Projects). Then interview the owner, one question at a time, and stop when another question would only produce detail nobody needs:
5145
+ Before the first project of a new client, the client and the project are in SpecShot: a person adds them (Clients, then Projects), or you add them when the owner asks (create_client after list_clients shows the client is not there yet, then create_project). Then interview the owner, one question at a time, and stop when another question would only produce detail nobody needs:
5069
5146
 
5070
5147
  - Who they are: what the business does, its customers, its size, where it is, its website.
5071
5148
  - The people: names, exact titles, who has final say, who handles the day to day, anyone outside the company involved.
@@ -5219,7 +5296,7 @@ Load the agency-process skill with get_skill first if you have not this session.
5219
5296
  4. Read the etch_ready prompt. The owner runs the Etch Connector, turns on the AI Connector in Etch, opens the page and clicks Etch's AI button. Call get_etch_build with dryRun first, run its script with the connector, and tell the owner which fonts to install and which images to upload. The owner may instead press Build in Etch in the extension's side panel, the canvas dialog or the plugin's Etch panel.
5220
5297
  5. Refine by hand through the connector by the skill below, etch-structure, etch-css, etch-connector-runtime and etch-connector-gotchas (get_skill each).
5221
5298
  6. Record progress with update_concept_status (sent when you start, built when it is complete) and add_build_note. On WordPress, check_built_page compares the built page with the approved design.
5222
- 7. Never publish, deploy, or touch logins, plugins, themes, hosting or DNS: draft it and hand it over. Confirming a page live is the owner's.
5299
+ 7. Never publish and never go live, and never touch logins, plugins, themes, hosting or DNS: draft it and hand it over. When the owner asks, send drafts: send_to_wordpress takes the approved pages to their paired WordPress site as drafts, and get_wordpress_deploy says when the drafts are ready to review in WordPress. Going live is the owner's: they review the drafts there and press Go live in SpecShot.
5223
5300
 
5224
5301
  ---
5225
5302
 
package/dist/client.js CHANGED
@@ -1,3 +1,53 @@
1
+ /**
2
+ * The base address the token is sent to, or an error in plain words.
3
+ *
4
+ * The API token travels in a header on every request, so a plain http address would send it in the
5
+ * clear. Only https is accepted, except on this machine (localhost and 127.0.0.1, for development).
6
+ */
7
+ export function checkedBaseUrl(raw) {
8
+ let parsed;
9
+ try {
10
+ parsed = new URL(raw);
11
+ }
12
+ catch {
13
+ return { ok: false, error: "SPECSHOT_APP_URL is not a web address. Use https://specshot.cc or leave it unset." };
14
+ }
15
+ const local = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
16
+ if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && local)) {
17
+ return { ok: false, error: "SPECSHOT_APP_URL must start with https://. A plain http address would send your API token unprotected." };
18
+ }
19
+ if (parsed.username || parsed.password)
20
+ return { ok: false, error: "SPECSHOT_APP_URL must not hold a user name or password." };
21
+ return { ok: true, url: raw.replace(/\/$/, "") };
22
+ }
23
+ /**
24
+ * A request path, checked. Throws when it could reach another route than the one its tool names.
25
+ *
26
+ * Tools put ids from their arguments into the path (`/api/mcp/concepts/<id>/...`). An id such as
27
+ * `../projects/<id>/intelligence?` would turn a call the person approved into a call to another
28
+ * route with the same method. A path built from real ids never holds a `.` or `..` segment, a
29
+ * query, a fragment, a backslash or a space, so those are refused here, once, for every tool.
30
+ * Query values go through the `params` argument, which encodes them.
31
+ */
32
+ export function safePath(path) {
33
+ const bad = !path.startsWith("/api/mcp/") ||
34
+ /[?#\\\s]/.test(path) ||
35
+ [...path].some((c) => c.charCodeAt(0) < 0x20) ||
36
+ path.split("/").some((segment) => {
37
+ let decoded = segment;
38
+ try {
39
+ decoded = decodeURIComponent(segment);
40
+ }
41
+ catch {
42
+ return true;
43
+ }
44
+ return decoded === "." || decoded === ".." || decoded.includes("/") || decoded.includes("\\");
45
+ }) ||
46
+ path.includes("//");
47
+ if (bad)
48
+ throw new Error("One of the ids is not valid. Pass ids exactly as SpecShot gave them.");
49
+ return path;
50
+ }
1
51
  /** Thin HTTP client for the SpecShot /api/mcp/* routes, authed by an API token. */
2
52
  export class SpecShotClient {
3
53
  baseUrl;
@@ -7,7 +57,7 @@ export class SpecShotClient {
7
57
  this.token = token;
8
58
  }
9
59
  async get(path, params) {
10
- const url = new URL(`${this.baseUrl}${path}`);
60
+ const url = new URL(`${this.baseUrl}${safePath(path)}`);
11
61
  if (params) {
12
62
  for (const [k, v] of Object.entries(params)) {
13
63
  if (v !== undefined && v !== "")
@@ -24,7 +74,7 @@ export class SpecShotClient {
24
74
  return res.json();
25
75
  }
26
76
  async patch(path, body) {
27
- const res = await fetch(`${this.baseUrl}${path}`, {
77
+ const res = await fetch(`${this.baseUrl}${safePath(path)}`, {
28
78
  method: "PATCH",
29
79
  headers: {
30
80
  Authorization: `Bearer ${this.token}`,
@@ -39,7 +89,7 @@ export class SpecShotClient {
39
89
  return res.json();
40
90
  }
41
91
  async post(path, body) {
42
- const res = await fetch(`${this.baseUrl}${path}`, {
92
+ const res = await fetch(`${this.baseUrl}${safePath(path)}`, {
43
93
  method: "POST",
44
94
  headers: {
45
95
  Authorization: `Bearer ${this.token}`,