@rubytech/create-maxy-code 0.1.398 → 0.1.400

package/payload/platform/plugins/web-designer/skills/web-design/references/e-sign.md

@@ -0,0 +1,39 @@
+# E-signing
+
+When a deployed page carries a document that must be signed — a quote, a proposal,
+terms, a contract — the signing is owned end to end by the `business-assistant:e-sign`
+skill. This plugin routes to it; it does not re-implement any signing, recording,
+stamping, or dispatch mechanics, because those carry a legal and compliance basis
+that must not be forked.
+
+## What e-sign owns
+
+`business-assistant:e-sign` deploys the document to Cloudflare Pages keyed by a
+`DOC_REF`, captures a signer's name, email, and an intent-and-consent tick through
+a Pages Function into a shared D1 `acceptances` table (with a one-acceptance-per-
+document database lock), renders a base PDF once and stamps an Electronic
+Acceptance Certificate onto it at dispatch, and emails the stamped PDF to owner and
+signer — inside a live operator session only. Its legal basis is a simple
+electronic signature admissible under UK ECA 2000 s.7 and the simple-signature tier
+of UK eIDAS. Its full outcome contract and failure signals are in that skill.
+
+## The hand-off
+
+1. Build and deploy the document page as its own site (this plugin's `web-design`
+   plus `references/deploy.md`), so it has a stable URL.
+2. Load `business-assistant:e-sign` and let it take over capture, D1 recording,
+   PDF stamping, and dispatch for that `DOC_REF`.
+3. If the document must also sit behind a login, apply `references/gating.md`
+   first — gate the document path **and** the `/api/*` signing endpoints on the
+   same origin, and confirm the gate-probe.
+
+Immutability holds: once a `DOC_REF` has an acceptance recorded, the deployed
+document is never edited. Changed terms are a new `DOC_REF` and a fresh deploy.
+
+## Editions
+
+E-signing is the one feature that is **not** self-contained in the marketplace
+edition. It depends on the `business-assistant:e-sign` skill being present on the
+host. A standalone install that needs signing must carry that skill; without it,
+this plugin builds and deploys the document but does not sign it. This is a stated
+host dependency, not a silent gap.

package/payload/platform/plugins/web-designer/skills/web-design/references/gating.md

@@ -0,0 +1,55 @@
+# Gated access (Cloudflare Access)
+
+Put a deployed page — or one document path on it — behind a login. This composes
+the proven Cloudflare Access pattern; it authors no new gating mechanics. The
+complete, operationally-validated steps live in the host references:
+
+- `cloudflare/references/api.md` § Access — token minting and the Access app +
+  policy endpoints (`POST /accounts/${ACC}/access/apps`,
+  `.../apps/{app_id}/policies`), with the Access token resolved by
+  `cf-token.sh access`.
+- `business-assistant/skills/e-sign/SKILL.md` § 1a — the full gating design,
+  proven on real deployments.
+
+Follow those. This note names the load-bearing invariants so a gating run does not
+skip one.
+
+## The invariants that make or break a gate
+
+- **Identity provider first.** An Access app and policy do not enable a login
+  method. If zero identity providers exist when the gate goes live, the login page
+  offers nothing and locks everyone out, including the operator. List providers
+  (`GET /accounts/${ACC}/access/identity_providers`) and confirm the set is
+  non-empty before creating the app. For external visitors who belong to no
+  organisation, **One-Time PIN** is the correct provider — it emails a code to any
+  allowlisted address.
+- **Gate the document path and `/api/*` together, same origin.** Gate the document
+  path(s) and the form/signing endpoints (`/api/*`), and leave `/` and static
+  assets public so the neutral root portal loads without a PIN. Gating only the
+  document path is a bypass: anyone can POST to an ungated `/api/*` and forge a
+  submission. The `/api/*` handlers must be Pages Functions of the **same** Pages
+  project as the gated document — a second origin escapes the gate.
+- **Verify with a gate-probe.** Unauthenticated (no Access session, no cookies),
+  POST and GET each `/api/*` endpoint against the live origin. Each must return
+  **302** (Access login) or **403** — never 200/400/409/500 (those are
+  function-originated and prove the API is ungated). This is the only check that
+  catches a split-origin escape.
+- **Ship a neutral root portal.** A gated host must serve a `/` page: Cloudflare
+  lands visitors on the bare root after logout and sometimes after login, so no `/`
+  page is a 404 on a client-facing site. The root names no document, branches on no
+  auth state, and needs zero change when a second gated document is added. Build
+  logout links as `/cdn-cgi/access/logout?returnTo=https://<host>/` (camelCase
+  `returnTo`, pointing at the public root).
+- **Token caveats.** "Access: Apps and Policies Write" can resolve to more than one
+  permission-group id; the wrong one poisons the token (a persistent `10000` on
+  every call). Verify a freshly-minted Access token with a read
+  (`GET /accounts/${ACC}/access/apps`) before relying on it. Update apps with
+  `PUT` and the full body, not `PATCH` (`PATCH` returns `10405` under API-token
+  auth). `cf-token.sh access` already handles the poison-id retry.
+
+## Editions
+
+The token is resolved through the same seam as deploy (`bin/resolve-cf.sh
+token-key`), so gating works in both editions once an Access-scoped token is
+available. Inside maxy-code that token is minted and persisted by
+`cf-token.sh access`; standalone it is an Access-scoped `CLOUDFLARE_API_TOKEN`.

package/payload/platform/plugins/web-designer/skills/web-design/references/placeholders.md

@@ -0,0 +1,110 @@
+# Placeholder reference
+
+Every `{{ TOKEN }}` in the templates and what fills it. After substitution,
+`grep "{{"` across the output must return nothing. Never invent a value — if a
+token has no source, go back to the operator and ask.
+
+## Brand tokens (palette) — from `brand-extract`
+
+`INK_900` `INK_700` `INK_400` (text: primary / secondary / muted) ·
+`PAPER_100` `PAPER_200` (white surface / page-bg tint) · `RULE_100` (dividers) ·
+`ACCENT` (brand accent) · `ACCENT_TEXT` (accent **deepened** for legible small
+text) · `ACCENT_SOFT` (pale accent wash) · `BRAND_GREY` (logo grey).
+
+## Identity
+
+`COMPANY_NAME` (trading name) · `COMPANY_LEGAL_NAME` · `COMPANY_SHORT` (monogram /
+initials) · `TAGLINE` · `SECTOR_LABEL` (what the business is, e.g. "Chartered
+accountants", "Dental practice", "Design studio" — operator-supplied, no default
+category) · `ESTABLISHED_YEAR` · `YEARS_TRADING` (e.g. "over 15 years") ·
+`OWNERSHIP` (e.g. "Independently owned") · `COMPANY_NUMBER` ·
+`COMPANY_NUMBER_LABEL` (what to call that number in structured data — e.g.
+"Company number" in the UK, "EIN" in the US; jurisdiction-driven, no country
+baked in) · `COMPANY_JURISDICTION` · `COPYRIGHT_YEAR`.
+
+## Contact & place
+
+`PHONE_DISPLAY` `PHONE_TEL` `PHONE_INTL` · `MOBILE_DISPLAY` `MOBILE_TEL` ·
+`EMAIL` · `WEBSITE_URL` (note the trailing slash; `og:image` and JSON-LD build on
+it) · `STREET_ADDRESS` `POST_TOWN` `LOCALITY` `COUNTY` `POSTCODE` · `COUNTRY_CODE` (the ISO 3166-1 alpha-2 country for the
+JSON-LD `addressCountry`, e.g. `GB`, `US`, `IE` — operator-supplied, no country
+baked in) · `REGION` (service-area phrase) `REGION_2` (secondary area) ·
+`FACEBOOK_URL` `INSTAGRAM_URL` `TIKTOK_URL`.
+
+## Hero info-card
+
+`HERO_STRAPLINE` · `HERO_META` (the one-line summary of what the business offers) ·
+`HERO_SPEC_1..4` (four short credential cells). `HERO_1_ALT..HERO_10_ALT` are the
+ten hero-slide alts — rewrite each to describe the real photo.
+
+## Body blocks (Story / What we do / How we work)
+
+`STORY_HEADLINE` `STORY_PARA_1` `STORY_PARA_2` ·
+`BUILD_HEADLINE` `BUILD_PARA_1..3` (the "What we do" block; each paragraph may open
+with a `<strong>lead-in.</strong>`) ·
+`CRAFT_HEADLINE` `CRAFT_PARA_1..3` (the "How we work" block).
+
+The `BUILD_*` / `CRAFT_*` token names are historical; the visible sections read
+**What we do** and **How we work**. Fill them with the business's real offer and
+way of working, in plain language.
+
+## Photo alts (grids and full-bleed)
+
+`GRID_1_ALT..GRID_12_ALT` (the photo-grid cells, in document order) ·
+`FULLBLEED_1_ALT` (the one full-width intermission image). Rewrite every alt to
+the real photo; the template ships none baked in.
+
+## Founder / team-lead section
+
+`FOUNDER_SECTION_LABEL` (eyebrow) · `FOUNDER_NAME` · `FOUNDER_PORTRAIT_ALT` ·
+`FOUNDER_HEADLINE` `FOUNDER_INTRO` `FOUNDER_QUOTE` `FOUNDER_ETHOS` ·
+`FEATURE_PROJECT_ALT` `FEATURE_PROJECT_CAPTION` · `GIFT_ALT` `GIFT_CAPTION` ·
+`UPDATES_LABEL` (defaults to "Latest updates") · `UPDATE_1..3_LOC`
+`UPDATE_1..3_TEXT` (short "latest update" cards). This whole section is optional —
+drop it when the business has no single figurehead.
+
+## Testimonial
+
+`TESTIMONIAL_ALT` (the image beside the quote) · `TESTIMONIAL_QUOTE` (verbatim;
+wrap the highlight clause in `<span class="hl">…</span>`) · `TESTIMONIAL_ATTRIB` ·
+`TESTIMONIAL_CONTEXT` · `FOUNDER_AVATAR_ALT` (the small round avatar).
+
+## Services
+
+`SERVICES_HEADLINE` `SERVICES_LEDE` · `SERVICE_1..6_NAME` `SERVICE_1..6_DESC` ·
+`OFFER_CATALOG_NAME` (JSON-LD). Use fewer than six by deleting surplus service
+cells rather than padding.
+
+## Why-us / key facts
+
+`WHY_HEADLINE` · `FACT_1..6_KEY` `FACT_1..6_VALUE` · `FACTS_FOOTNOTE`. (The first
+fact row, "Established", uses `ESTABLISHED_YEAR`; Coverage uses `REGION`; Based
+uses `LOCALITY`/`COUNTY`.)
+
+## FAQ (visible + JSON-LD use the same tokens)
+
+`FAQ_1..5_Q` `FAQ_1..5_A`. Answer-first: the first sentence of each answer is the
+answer-engine lift target.
+
+## CTA / footer / meta / schema
+
+`CTA_HEADLINE` · `FOOTER_LABEL` `FOOTER_LEGAL` · `META_DESCRIPTION`
+`META_DESCRIPTION_SHORT` · `SCHEMA_TYPE` `SCHEMA_DESCRIPTION` · `PAGE_LANG` (the
+`<html lang>` BCP-47 tag, e.g. `en-GB`, `en-US`, `fr` — operator-supplied, no
+locale baked in).
+
+`SCHEMA_TYPE` is the schema.org type for the business and is **operator-supplied**.
+Its default is `LocalBusiness` (use `Organization` for a business with no physical
+premises, or a more specific schema.org subtype when one fits — `Dentist`,
+`AccountingService`, `ProfessionalService`, and so on). No trade or industry type
+is baked in as a default.
+
+## llms.txt
+
+`LLMS_SUMMARY` (the one-paragraph elevator summary) · `RECENT_PROJECTS`.
+
+## Social tiles
+
+The `socials` skill owns its own tokens and template set. It reads the built
+`site/` (brand tokens, logo, hero photos) as its source; it does not add tokens to
+these templates. See [`../../socials/SKILL.md`](../../socials/SKILL.md).

package/payload/platform/plugins/web-designer/skills/web-design/references/sections.md

@@ -0,0 +1,52 @@
+# Section catalogue & image map
+
+The single page runs top to bottom in this order. Each section is in the canonical
+`templates/index.html`; this is the map, not a rebuild instruction.
+
+| # | Section | What it is | Images |
+|---|---|---|---|
+| 1 | Top nav | Centred logo, deep links left, utility links right; collapses to a hamburger drawer ≤ 1240px | `logo.png` |
+| 2 | Hero | Up to 10-slide JS rotator with a slow Ken-Burns push-in (reduced-motion holds slide 1); floating info-card with tag, name, strapline, tagline, four credential cells, links, CTA | `hero-01..10.webp` |
+| 3 | Sticky sub-nav | Reveals after the hero scrolls past | — |
+| 4 | About (Story) | Eyebrow + headline + two drop-capped paragraphs | grid after: `grid-01..04` |
+| 5 | What we do | Headline + three paragraphs (each a `<strong>` lead-in) | grids: `grid-05..08` |
+| 6 | How we work | Headline + three paragraphs | full-bleed `fullbleed-01`; grid `grid-09..12` |
+| 7 | Founder / team-lead | Portrait + intro + quote + ethos; a feature image and a second figure, bottom-aligned; three "latest update" cards. Optional — drop when there is no single figurehead | `founder-portrait`, `feature-project`, `gift` |
+| 8 | Testimonial | Dark band: an image + verbatim client quote (highlight clause) + small avatar | `testimonial`, `founder-avatar` |
+| 9 | Services | 3×2 grid of up to six services (name + one-line description) | — |
+| 10 | Why-us / key facts | 3-column grid of six key/value facts + footnote | — |
+| 11 | FAQ | Answer-first Q/A (matched by `FAQPage` JSON-LD) — answer-engine lift targets | — |
+| 12 | CTA strip | Accent band: tagline eyebrow, headline, phone / mobile / enquiry | — |
+| 13 | Footer | Contact column + legal paragraph (bottom-aligned) + colophon with the icon | `icon.png` |
+| — | Back-to-top | Fixed button, fades in past the hero | — |
+
+The section anchors are `#story` (About), `#offer` (What we do), `#how` (How we
+work), `#founder`, `#words` (Testimonial), `#services`, `#facts`, `#faq`.
+
+## Image-naming convention
+
+Curate the operator's photos into these names under `site/images/` (webp):
+
+- `hero-01..hero-10` — rotator. Pick varied, strong shots; lead with the best
+  "arrive here" image. The rotator cycles however many `.hero-slide` elements
+  exist, so fewer than 10 is fine — just delete the surplus slides.
+- `grid-01..grid-12` — photo grids, in document order.
+- `fullbleed-01` — the one full-width intermission image (a wide, strong shot).
+- `founder-portrait` (tall) and `founder-avatar` (square crop) — the person, if
+  the business has a figurehead.
+- `feature-project`, `gift` — the founder-section feature image and second figure.
+- `testimonial` — the image beside the client quote.
+- `logo.png`, `icon.png` — from `brand-extract`.
+
+A photo of a **person** belongs only in the founder/testimonial slots and the
+portrait social tile. It is never a hero-rotator landscape crop (the head gets cut).
+
+## Honesty notes
+
+- The 10-slide hero and the full grid set assume a reasonably deep photo library.
+  With fewer photos, reduce slides and drop grids rather than repeating images.
+- Alts must describe the actual photo. The template ships alt **tokens**, not
+  sentences — every `{{ *_ALT }}` is filled from the real image, verified by eye,
+  never trusted from a filename.
+- The founder section, the testimonial, and any service cell can be dropped when
+  the business does not have that thing. A shorter honest page beats a padded one.