@owlmeans/viable-common 0.0.25 → 0.0.27

package/src/scaffold/schemas.ts

@@ -1,9 +1,10 @@
 import type { JSONSchemaType } from 'ajv'
 
 import { ProjectArea } from '../areas/consts.js'
-import { WidgetKind } from './consts.js'
+import { BENTO_FRAGMENT_KINDS, WidgetKind } from './consts.js'
 import type {
-  GuestHomePlan, ProductIdentity, ScaffoldAreaPlan, ScaffoldPlan, ScaffoldStoryPlan, SketchContent,
+  BentoFragment, GuestHomePlan, LandingGatePlan, ProductIdentity,
+  ScaffoldAreaPlan, ScaffoldPlan, ScaffoldStoryPlan, SketchContent,
 } from './types.js'
 
 const SketchContentSchema: JSONSchemaType<SketchContent> = {
@@ -160,6 +161,166 @@ const ScaffoldAreaPlanSchema: JSONSchemaType<ScaffoldAreaPlan> = {
   additionalProperties: false,
 }
 
+/**
+ * Every property added to the guest home after the first stored plans is OPTIONAL and `nullable`.
+ *
+ * This schema is not only what a model answers with: it is the validator of the project card's
+ * `scaffold` document (`VIABLE_PROJECT_SLOTS`), so a plan written before a field existed must
+ * still pass it whenever that plan is carried into a new revision. A field made required here is a
+ * project whose plan can no longer be revised.
+ *
+ * Counts ("four tiles", "5–8 chips") are stated in the descriptions and CLAMPED in code — never
+ * `minItems`/`maxItems`, which a provider's structured output refuses or ignores, and never a
+ * tuple.
+ */
+const nullableLink = (description: string) => ({
+  type: 'object' as const,
+  nullable: true as const,
+  description,
+  properties: {
+    label: { type: 'string' as const, description: 'The link text, a verb first, 2-4 words' },
+    href: {
+      type: 'string' as const, nullable: true as const,
+      description: 'OPTIONAL, normally omitted: absent means the default action (sign in, or a'
+        + ' section of this page). Never invent an address'
+    },
+  },
+  required: ['label'] as 'label'[],
+  additionalProperties: false,
+})
+
+const BentoFragmentSchema: JSONSchemaType<BentoFragment> = {
+  type: 'object',
+  description: 'A small piece of the product\'s own interface drawn at the bottom of the tile, built'
+    + ' from its own records - never a paragraph',
+  properties: {
+    kind: {
+      type: 'string',
+      enum: BENTO_FRAGMENT_KINDS,
+      description: 'list (label + value rows, e.g. ingredients and amounts), note (one short remark'
+        + ' in the label), people (name in the label, role in the value), steps (numbered labels)'
+    },
+    title: {
+      type: 'string', nullable: true,
+      description: 'OPTIONAL small caption over the fragment, e.g. "INGREDIENTS · 1 LOAF"'
+    },
+    rows: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          label: { type: 'string', description: 'The row\'s main text, a few words' },
+          value: {
+            type: 'string', nullable: true,
+            description: 'The row\'s second column - an amount, a role; omit it for note and steps'
+          },
+        },
+        required: ['label'],
+        additionalProperties: false,
+      },
+      description: '2-4 rows of realistic records of this product'
+    },
+  },
+  required: ['kind', 'rows'],
+  additionalProperties: false,
+}
+
+const LandingGatePlanSchema: JSONSchemaType<LandingGatePlan> = {
+  type: 'object',
+  title: 'LandingGatePlan',
+  description: 'The working entry into the key end-user workflow, drawn in the hero instead of the'
+    + ' call-to-action buttons: a guest makes a few picks, sees sample results ranked against them,'
+    + ' and signs in to continue with the picks carried over. Every text is in the end user\'s words',
+  properties: {
+    story: {
+      type: 'string',
+      description: 'The code of the landing story, copied EXACTLY as given to you. Never shown'
+    },
+    target: {
+      type: 'string', nullable: true,
+      description: 'Leave it out - the platform fills it'
+    },
+    question: {
+      type: 'string',
+      description: 'The question the gate asks, 3-6 words, in the end user\'s words - e.g. "What\'s'
+        + ' in your pantry?"'
+    },
+    hint: { type: 'string', description: 'A short reassurance beside it, e.g. "No account needed"' },
+    label: {
+      type: 'string',
+      description: 'The accessible name of the group of choices, 2-3 words - e.g. "Your pantry"'
+    },
+    inputs: {
+      type: 'array',
+      items: { type: 'string' },
+      description: '5 to 8 things a guest can pick, 1-3 words each, from the story\'s own domain.'
+        + ' Nothing personal, nothing sensitive, nothing that needs an account'
+    },
+    selected: {
+      type: 'array',
+      items: { type: 'string' },
+      description: '4 or 5 of the inputs above, copied exactly, pre-selected so the first view'
+        + ' already shows results'
+    },
+    results: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: 'A realistic record title, 2-4 words' },
+          meta: {
+            type: 'string',
+            description: 'One short line: how well it fits and one fact, e.g. "Uses all 3 · 3 h 20 min"'
+          },
+          needs: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '2-4 of the inputs above, copied exactly, that this record uses'
+          },
+        },
+        required: ['title', 'meta', 'needs'],
+        additionalProperties: false,
+      },
+      description: '3 or 4 sample records the picks are ranked against - illustrative, never real data'
+    },
+    count: {
+      type: 'object',
+      properties: {
+        one: { type: 'string', description: 'The count for one match, with {n}: "{n} bake matches"' },
+        many: { type: 'string', description: 'The count for several, with {n}: "{n} bakes match"' },
+        none: { type: 'string', description: 'The count for none, e.g. "No matches yet"' },
+      },
+      required: ['one', 'many', 'none'],
+      additionalProperties: false,
+      description: 'The live count label; write the literal token {n} where the number goes'
+    },
+    empty: {
+      type: 'string',
+      description: 'One line shown when nothing matches, saying what to pick - e.g. "Pick two or more'
+        + ' ingredients to see what you can bake."'
+    },
+    note: {
+      type: 'string',
+      description: 'One short line beside the button: signing in is by email and the picks come'
+        + ' along - e.g. "Sign in with your email. Your picks come with you."'
+    },
+    cta: {
+      type: 'string',
+      description: 'The button label, a verb first, 2-3 words and an arrow - e.g. "Open recipes →"'
+    },
+    lock: {
+      type: 'string',
+      description: 'What unlocks after sign-in, as the accessible name of a lock icon - e.g. "Full'
+        + ' method after sign-in"'
+    },
+  },
+  required: [
+    'story', 'question', 'hint', 'label', 'inputs', 'selected', 'results', 'count', 'empty',
+    'note', 'cta', 'lock',
+  ],
+  additionalProperties: false,
+}
+
 const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
   type: 'object',
   title: 'GuestHomePlan',
@@ -170,16 +331,27 @@ const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
       properties: {
         headline: {
           type: 'string',
-          description: 'The product\'s promise in one line, under 9 words. Never the product name alone'
+          description: 'The product\'s promise in one short concrete line, at most 6 words. Never the'
+            + ' product name alone'
+        },
+        sub: {
+          type: 'string',
+          description: 'One or two sentences: what it does and who it is for. No invented numbers'
+        },
+        cta: {
+          type: 'string',
+          description: 'The primary button label, a verb first, 2-3 words. Shown only when the page'
+            + ' has no gate'
         },
-        sub: { type: 'string', description: 'One or two sentences: what it does and who it is for' },
-        cta: { type: 'string', description: 'The call-to-action label, 2-3 words' },
         eyebrow: {
           type: 'string', nullable: true,
-          description: 'OPTIONAL, normally omitted. A small badge above the headline - set it only when'
-            + ' the specification explicitly asks for a label there. A landing page carries no badge by'
-            + ' default: the headline is what positions the product'
+          description: 'Omit it. The page shows no badge above the headline; the headline is what'
+            + ' positions the product'
         },
+        secondary: nullableLink('OPTIONAL second button beside the primary one, when there is no'
+          + ' gate - e.g. "Browse bakes"'),
+        browse: nullableLink('OPTIONAL muted link under the gate or the buttons for someone not'
+          + ' ready to start - the whole line, e.g. "Just browsing? Explore bakes"'),
       },
       required: ['headline', 'sub', 'cta'],
       additionalProperties: false,
@@ -213,11 +385,13 @@ const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
         properties: {
           title: { type: 'string', description: 'The capability, 2-4 words' },
           text: { type: 'string', description: 'One sentence on what it lets someone do' },
+          fragment: { ...BentoFragmentSchema, nullable: true },
         },
         required: ['title', 'text'],
         additionalProperties: false,
       },
-      description: '3 to 6 capabilities, taken from what the specification actually describes'
+      description: '4 capabilities - the bento tiles "What you get" - taken from what the'
+        + ' specification actually describes. Give most of them a fragment'
     },
     testimonials: {
       type: 'array',
@@ -231,7 +405,80 @@ const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
         required: ['quote', 'name', 'role'],
         additionalProperties: false,
       },
-      description: '2 or 3 illustrative testimonials'
+      description: '2 illustrative testimonials. No ratings, no numbers, no company names'
+    },
+    steps: {
+      type: 'array', nullable: true,
+      items: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: 'The step as an action, 2-5 words' },
+          text: { type: 'string', description: 'One short sentence on what happens in it' },
+        },
+        required: ['title', 'text'],
+        additionalProperties: false,
+      },
+      description: '"How it works": 3 steps taken from the main flow, in order, the last one'
+        + ' delivering the value'
+    },
+    labels: {
+      type: 'object', nullable: true,
+      description: 'The small label over each section and that section\'s heading, in the product\'s'
+        + ' language. Labels are 1-3 plain words; headings are one short concrete sentence',
+      properties: {
+        steps: { type: 'string', nullable: true, description: 'e.g. "How it works"' },
+        stepsTitle: {
+          type: 'string', nullable: true,
+          description: 'e.g. "From pantry to proofing basket in three steps."'
+        },
+        features: { type: 'string', nullable: true, description: 'e.g. "What you get"' },
+        featuresTitle: {
+          type: 'string', nullable: true, description: 'e.g. "Everything behind the bake."'
+        },
+        testimonials: { type: 'string', nullable: true, description: 'e.g. "Community"' },
+        testimonialsTitle: {
+          type: 'string', nullable: true, description: 'e.g. "Bakers who made it at home."'
+        },
+        problem: { type: 'string', nullable: true, description: 'e.g. "The problem"' },
+        solution: { type: 'string', nullable: true, description: 'e.g. "The solution"' },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+    closing: {
+      type: 'object', nullable: true,
+      description: 'The closing band at the foot of the page',
+      properties: {
+        headline: { type: 'string', description: 'A short invitation, at most 6 words' },
+        lead: { type: 'string', description: 'One or two sentences under it' },
+        primary: { type: 'string', description: 'The primary button label, a verb first, 2-4 words' },
+        secondary: nullableLink('OPTIONAL second button, e.g. "Browse bakes"'),
+        links: {
+          type: 'array', nullable: true,
+          items: {
+            type: 'object',
+            properties: {
+              title: { type: 'string', description: 'What the card leads to, 2-3 words' },
+              text: { type: 'string', description: 'One short line about it' },
+              href: {
+                type: 'string', nullable: true,
+                description: 'OPTIONAL, normally omitted. Never invent an address'
+              },
+            },
+            required: ['title', 'text'],
+            additionalProperties: false,
+          },
+          description: '2 link cards beside the closing headline'
+        },
+      },
+      required: ['headline', 'lead', 'primary'],
+      additionalProperties: false,
+    },
+    gate: {
+      ...LandingGatePlanSchema,
+      nullable: true,
+      description: 'ONLY when you were given a landing story; omit it otherwise. '
+        + LandingGatePlanSchema.description,
     },
   },
   required: ['hero', 'problem', 'solution', 'features', 'testimonials'],
@@ -278,9 +525,11 @@ export const ScaffoldPlanSchema: JSONSchemaType<ScaffoldPlan> = {
     },
     motifs: {
       type: 'string',
-      description: 'Two or three sentences directing this product\'s illustrations: what shapes'
-        + ' and subjects belong to it, in the design system\'s own vocabulary. Abstract geometry,'
-        + ' never a described photograph'
+      description: 'Two or three sentences describing this product\'s hero illustration as a SCENE:'
+        + ' one main object of its domain resting on a surface, one or two smaller objects beside'
+        + ' it, and one simplified piece of the product\'s interface, each in its natural muted'
+        + ' colours. Concrete recognisable objects - never abstract geometry, never floating'
+        + ' circles, rings or dots, never people, text or a described photograph'
     },
   },
   required: ['identity', 'guestHome', 'areas', 'stories', 'motifs'],

package/src/scaffold/types.ts

@@ -89,22 +89,122 @@ export interface ProductIdentity {
   description: string
 }
 
+/**
+ * A labelled link on the landing page — a secondary pill, the "just browsing" link, a closing card.
+ *
+ * `href` is OPTIONAL and normally absent: absent means the default action the stamper decides
+ * (start sign-in, or jump to a section of the page itself). A model never knows the application's
+ * addresses, and an invented one is a link that 404s on the public face of the product.
+ */
+export interface PlanLink {
+  label: string
+  href?: string
+}
+
+/** The four shapes a bento tile's product fragment can take — each one a stamped primitive. */
+export type BentoFragmentKind = 'list' | 'note' | 'people' | 'steps'
+
+/**
+ * A small piece of the product's own interface, drawn at the bottom of a bento tile.
+ *
+ * Structured for the same reason {@link SketchContent} is: the fragment is STAMPED, so it must be
+ * rows a component can lay out, never a paragraph describing them. Built from the product's own
+ * records, and decorative — the stamper renders it `aria-hidden`.
+ */
+export interface BentoFragment {
+  kind: BentoFragmentKind
+  /** Small caption over the fragment ("INGREDIENTS · 1 LOAF", "Baker's note"). */
+  title?: string
+  /** list: {label, value}; note: {label: text}; people: {label: name, value: role}; steps: {label}. */
+  rows: { label: string, value?: string }[]
+}
+
+/**
+ * The landing gate — the working entry into the product's key END-USER workflow, drawn in the
+ * hero where the call-to-action pills would otherwise be.
+ *
+ * A guest makes a few non-sensitive choices on the landing page, sees sample results ranked
+ * against them, and signs in to continue on the story's full-scale screen with those choices
+ * carried over. Every field is copy or sample data in the end user's own words; nothing here is
+ * an address the model invented — `target` is filled by code.
+ */
+export interface LandingGatePlan {
+  /** The key end-user story's code — never rendered. */
+  story: string
+  /** Entrypoint ALIAS of the story's full-scale screen in the user area (filled by code, not the model). */
+  target?: string
+  /** The question the gate asks, in the end user's words: "What's in your pantry?". */
+  question: string
+  /** The reassurance beside it: "No account needed". */
+  hint: string
+  /** The accessible name of the chip group: "Your pantry". */
+  label: string
+  /** 5–8 chip labels the guest picks from. */
+  inputs: string[]
+  /** 4–5 of `inputs`, pre-selected so the first view already shows results. */
+  selected: string[]
+  /** 3–4 sample records; `needs` is the subset of `inputs` each one uses. */
+  results: { title: string, meta: string, needs: string[] }[]
+  /** The live count label; `{n}` is replaced by the number ("{n} bakes match"). */
+  count: { one: string, many: string, none: string }
+  /** The line shown when nothing matches the picks. */
+  empty: string
+  /** The line beside the CTA: "Sign in with your email. Your picks come with you.". */
+  note: string
+  /** The CTA label: "Open recipes →". */
+  cta: string
+  /** The accessible name of a result row's lock icon: "Full method after sign-in". */
+  lock: string
+}
+
 /** The guest area's landing page — the product's public face. */
 export interface GuestHomePlan {
   hero: {
     headline: string
     sub: string
+    /** The primary pill's label — shown only when the page has no {@link GuestHomePlan.gate}. */
     cta: string
     /**
-     * A badge above the headline — OPTIONAL and normally absent. A landing page carries no badge
-     * unless its specification asks for one; the headline is what positions the product.
+     * A badge above the headline — OPTIONAL and kept only so an older stored plan still reads.
+     * The page renders no badge: the headline is what positions the product.
      */
     eyebrow?: string
+    /** The second pill beside the primary one, when there is no gate. */
+    secondary?: PlanLink
+    /** The muted text link under the gate or the pills: "Just browsing? Explore bakes ›". */
+    browse?: PlanLink
   }
   problem: { title: string, text: string }
   solution: { title: string, text: string }
-  features: { title: string, text: string }[]
+  /** The bento tiles — four, each optionally anchored by a fragment of the product's interface. */
+  features: { title: string, text: string, fragment?: BentoFragment }[]
   testimonials: { quote: string, name: string, role: string }[]
+  /** "How it works" — three steps taken from the main flow. */
+  steps?: { title: string, text: string }[]
+  /** The small section labels and section headings; absent ones fall back to the stamper's own. */
+  labels?: {
+    steps?: string
+    stepsTitle?: string
+    features?: string
+    featuresTitle?: string
+    testimonials?: string
+    testimonialsTitle?: string
+    problem?: string
+    solution?: string
+  }
+  /** The closing band: a headline, a lead, the two pills and two link cards. */
+  closing?: {
+    headline: string
+    lead: string
+    primary: string
+    secondary?: PlanLink
+    links?: { title: string, text: string, href?: string }[]
+  }
+  /**
+   * The landing gate — present only when a gate story was decided for the project. When it is,
+   * it REPLACES the hero's pills.
+   */
+  gate?: LandingGatePlan
 }
 
 /**
@@ -120,8 +220,8 @@ export interface ScaffoldPlan {
   areas: ScaffoldAreaPlan[]
   stories: ScaffoldStoryPlan[]
   /**
-   * How this product's illustrations should look — geometry and motif, in the design system's
-   * own vocabulary. The one field here that is prose, because it is read by a model.
+   * How this product's illustrations should look — the scene, its domain objects and their
+   * palette. The one field here that is prose, because it is read by a model.
    */
   motifs: string
 }

package/src/skills/catalogue.ts

@@ -596,39 +596,66 @@ carries. Introducing a second spelling orphans every grant made against the firs
   files, not a copy of their own. They are already there: import them, never delete, rename or
   move one, and never re-add a primitive the directory already carries.
 - Styling is Tailwind utility classes. There are no CSS modules and no styled-components.
+- The GROUND is white in light mode and black in dark mode, and it stays that way: every page,
+  section, band and header sits on \`bg-background\`. Colour comes from ONE product accent —
+  \`bg-primary\` / \`text-primary\` — and only on the primary button, a section's small label, the rule
+  over the first step and a check mark. It never comes from a background, a tint or a band.
+
+      <section className="bg-primary/10 py-20">...</section>                       // WRONG
+      <section className="bg-gradient-to-b from-amber-50 to-white py-20">...</section>  // WRONG
+      <section className="border-t py-20">...</section>                            // right
+
+- Depth comes from exactly three things: a 1px HAIRLINE (\`border\`, the \`--border\` token), the
+  NEUTRAL TILE (\`bg-muted\` — the only tinted surface: feature tiles, testimonial tiles, result
+  rows), and ONE shadow, \`shadow-floating\`, which belongs to the one card that floats (the landing
+  gate). An ordinary card is \`rounded-xl border bg-card\` and carries no shadow. There are no
+  gradients, no glass, no backdrop blur, no glow and no coloured shadows anywhere in the interface.
+
+      <div className="rounded-xl bg-white/60 shadow-2xl backdrop-blur-md p-6" />  // WRONG
+      <div className="rounded-xl border bg-card p-6" />                           // right
+      <li className="rounded-[32px] bg-muted p-10" />                             // right — a tile
+
+- TYPE carries the brand. Headings are the theme's heavy grotesk — \`font-extrabold\` with tight
+  negative tracking (\`tracking-tight\`, or \`tracking-[-0.045em]\` on a section heading) and
+  \`text-balance\`; paragraphs are \`text-muted-foreground\` with \`text-pretty\` and a readable
+  measure (\`max-w-[52ch]\`); whitespace is generous. Never set a different font family.
+- A section opens with a small LABEL — a plain \`<p className="text-[15px] font-bold text-primary">\`
+  — then its \`<h2>\`. A label is text: never a chip, a pill or a badge.
+- Buttons are pills. The primary one is \`cta-btn\` (on an \`<a>\` or a bare \`<button>\`, never on a
+  shadcn \`Button\`, whose own \`bg-\` utility would win); the secondary one is
+  \`rounded-full border-[1.5px] border-foreground text-foreground hover:bg-muted\`. Labels are verbs.
+- Motion is small and belongs to the picture: \`reveal\` fades a block in once as it enters, and
+  \`float-slow\` / \`drift-slow\` lift PARTS OF AN ILLUSTRATION by a few pixels. Nothing spins,
+  pulses, orbits or scales, and nothing moves for someone who asked for reduced motion.
+- The stylesheet still defines the older classes \`gradient-heading\`, \`glass-card\`, \`eyebrow\`,
+  \`glow-orb\`, \`shadow-soft\`, \`shadow-raised\`, \`shadow-glow\`, \`pulse-soft\` and \`spin-slow\`,
+  because screens written earlier use them. They are REPAINTED flat — \`gradient-heading\` is solid
+  ink, \`glass-card\` a neutral tile, \`eyebrow\` a plain accent label, \`glow-orb\` hidden, the three
+  shadows and the two animations nothing at all. Never reach for one of them as decoration: it
+  paints nothing, or it paints the flat thing you could have written directly. Do not invent other
+  classes in the same family.
+- Overrides: change any of the look rules above — the ground, the accent, depth, type, motion —
+  ONLY when the customer's specification explicitly asks: it names a background colour, a
+  dark-only or coloured theme, a brand palette, or gradients. The product's subject matter is not
+  a request — a bakery is not a warm background and a bank is not a blue one.
 - Colour comes in PAIRS. Every surface token in this theme has a foreground partner —
   \`--background\`/\`--foreground\`, \`--card\`/\`--card-foreground\`, \`--primary\`/\`--primary-foreground\`,
   and the same for \`secondary\`, \`muted\`, \`accent\`, \`popover\`, \`destructive\` and \`sidebar\`. Painting a
   surface is therefore never a single decision: give the element its partner in the SAME
   \`className\`, or the text keeps the colour meant for the surface underneath and vanishes wherever
-  the design made that surface dark.
+  that surface is dark.
 
-      <section className="bg-primary p-6">Join us</section>                         // WRONG
-      <section className="bg-primary text-primary-foreground p-6">Join us</section>  // right
+      <a className="rounded-full bg-primary px-7 py-3">Get started</a>                          // WRONG
+      <a className="rounded-full bg-primary text-primary-foreground px-7 py-3">Get started</a>  // right
 
-  Nothing catches the wrong form — it compiles and it renders. It is unreadable only on the
-  surfaces the design happened to make dark, which is why it survives to the finished screen.
+  Nothing catches the wrong form — it compiles and it renders. It is unreadable only where the
+  accent happens to be dark, which is why it survives to the finished screen.
 - Never paint a surface with a raw or palette colour — \`bg-slate-900\`, \`bg-[#101820]\`,
   \`style={{ background: '#101820' }}\`. Those have no foreground partner, so nothing keeps the text
-  on them legible, and they ignore the theme. Every surface is one of the tokens above.
-- Depth and emphasis come from the theme's DECORATION VOCABULARY, and using it is expected rather
-  than exceptional — a screen built only from flat cards is an unfinished screen. That vocabulary
-  is: the component classes \`gradient-heading\` (a page or section headline), \`glass-card\` (a
-  panel with depth), \`eyebrow\` (the small chip above a headline), \`cta-btn\` (the primary call to
-  action, on an \`<a>\` or a bare \`<button>\`, never on a shadcn \`Button\` whose own \`bg-\`
-  utility would win), \`glow-orb\` (a soft colour field behind a section, always
-  \`pointer-events-none\` and behind the content); the elevation utilities \`shadow-soft\`,
-  \`shadow-raised\`, \`shadow-floating\`, \`shadow-glow\`; the idle-motion classes \`reveal\`,
-  \`float-slow\`, \`drift-slow\`, \`pulse-soft\`, \`spin-slow\`; and gradients whose stops are THEME
-  tokens with opacity. None of these is a raw colour.
-
-      <div className="bg-[radial-gradient(#818cf8,transparent)] blur-[120px]" />   // WRONG
-      <span className="glow-orb h-80 w-96 -z-10" aria-hidden />                    // right
-      <div className="bg-gradient-to-br from-primary/20 to-transparent p-6" />     // right
-
-  Keep a gradient under a text element light — \`/20\` or less — unless the element also carries a
-  \`-foreground\` partner class. These class names are defined in the project's stylesheet; do not
-  invent others in the same family.
+  on them legible, and they ignore the theme and its dark mode. Every surface is one of the tokens
+  above.
+- Every interactive element keeps its visible \`focus-visible\` ring, is at least 44px tall to touch,
+  and never signals anything by hover alone.
 - Text that is NOT on a coloured surface takes NO colour class: it already inherits the readable
   one. Never add \`text-white\`, \`text-black\` or a \`-foreground\` class "to be safe" — on an ordinary
   panel that is the same fault inverted. \`text-muted-foreground\` for secondary text is the
@@ -793,6 +820,84 @@ symbols from the component name (PascalCase of the component definition — for
 Both sides must use these exact names. This is a DEFAULT: when a "View-model contract"
 block is present in the task, it lists the symbols that actually exist and overrides this
 convention entirely.
+`),
+
+  skill(ViableSkill.LandingGate, 'The landing gate — from the landing page into the app', `
+A product can let a guest START its key end-user workflow on the landing page, before any account
+exists, and finish it in the app after signing in with the choices they made carried over. The
+card that does this is the LANDING GATE. It sits in the hero where the call-to-action buttons
+would be, and it REPLACES them.
+
+**Which story is gate-worthy.** At most ONE per project, and only a story that is all of:
+- in the \`user\` area — the signed-in END user's own workflow, never an operator's, an owner's or
+  one a guest already completes without signing in;
+- a FIRST-VALUE step — something useful comes out of it the moment the guest acts;
+- begun with NON-SENSITIVE input — a few picks, a filter, a short text. Never a payment, an
+  address, an upload, contact details or anything else about the person.
+A pantry-to-recipe finder is gate-worthy: pick ingredients, see what you can bake. Checking out a
+basket, setting up a profile or reviewing a queue of requests is not. When no story qualifies
+there is no gate and the hero keeps its buttons — a correct answer, not a failure.
+
+**The card.** The sketch is \`@/components/home/gate\`; the implemented one is
+\`@/components/home/landing-gate\` and exports the same \`LandingGate\` with the same props.
+- Its root is \`<div id="gate" data-home-gate>\` — never a \`<section>\`, \`<aside>\`, \`<header>\`
+  or \`<footer>\`; the page already has exactly one of each landmark it needs.
+- A question in the end user's words as its heading, and a "No account needed" hint beside it.
+- 5 to 8 choice chips, each a \`<button type="button" aria-pressed={selected}>\` inside a
+  \`role="group"\` with an \`aria-label\`, 4 or 5 pre-selected so the first view already shows
+  results. When choices do not fit, 1 to 3 labelled fields instead.
+- A count with \`aria-live="polite"\`, at most 2 result rows re-ranked on every change, and one
+  line for when nothing matches. A row's lock icon is named "Full details after sign-in".
+- A one-line note ("Sign in with your email. Your picks come with you.") and ONE primary button,
+  straight after the choices in tab order. No second button beside it.
+- The sketch works signed out and offline from its sample records. The implemented card may call
+  a PUBLIC endpoint; never one that needs a signed-in user.
+
+**The handoff.** The button carries the guest's choices across sign-in in \`sessionStorage\`,
+through \`@/lib/handoff\` — never in the URL, never in a cookie, never through the server:
+
+    import { useLandingStart } from '@/lib/handoff'
+
+    const start = useLandingStart(target)
+    <button type="button" className="cta-btn" onClick={() => start({ picks })}>{cta}</button>
+
+- \`target\` is the ALIAS of the story's own full-scale screen in the user area — the prop the guest
+  home passes — never a URL.
+- \`useLandingStart(target)\` is the whole button: it writes the handoff, then navigates to
+  \`target\` when the visitor is already signed in, or starts the ordinary sign-in otherwise. After
+  sign-in the guest home's \`Hero\` (\`useLandingContinuation\`) sends the visitor on to \`target\`.
+- NEVER \`useLogin(target)\` for the gate: its continuation navigates straight to the guarded screen,
+  which answers a signed-out visitor with "Sign in required", and that card's own sign-in lands on the
+  home page — the full-scale screen is never reached.
+- The handler \`useLandingStart\` returns is SYNCHRONOUS, and the click calls it in the same gesture.
+  A sign-in that has to open a window is eaten by the popup blocker once anything has been awaited.
+
+      onClick={async () => { await saveDraft(picks); start({ picks }) }}  // WRONG — the gesture is gone
+      href={'/frontoffice/recipes?picks=' + picks.join(',')}               // WRONG — a URL, the picks in it, no sign-in
+
+**The full-scale screen** — the story's own screen in the user area — reads the handoff once in its
+view model, pre-fills from it, says so in one line, and clears it:
+
+    import { clearLandingHandoff, readLandingHandoff } from '@/lib/handoff'
+
+    useEffect(() => {
+      const carried = readLandingHandoff<{ picks: string[] }>(alias)
+      if (carried == null) return
+      setPicks(carried.picks)
+      setCarriedOver(true)          // "We kept your 4 picks from the home page."
+      clearLandingHandoff()
+    }, [alias])
+
+\`alias\` is the screen's own alias — the same string the gate was given as \`target\`. A missing,
+expired or foreign handoff reads as \`null\`, and the screen then starts empty exactly as it does for
+someone who arrived from the menu; never treat its absence as an error.
+
+**Never:**
+- ask for an account, a payment, an email address or any personal detail before sign-in — the gate
+  collects choices and nothing else, and the handoff stores only those choices;
+- render a story code, a "Preview" badge or a dashed frame inside the gate — it is the product's
+  public face in production;
+- keep the hero's buttons beside a gate, or give the gate a second call to action.
 `),
 
   skill(ViableSkill.ResourceLayer, 'OwlMeans resources own the schema', `

package/src/skills/consts.ts

@@ -31,6 +31,11 @@ export enum ViableSkill {
   FormFeedback = 'form-feedback',
   StoreAccess = 'store-access',
   ViewModelNaming = 'viewmodel-naming',
+  /**
+   * The landing gate: a guest starts the key end-user story on the landing page and continues on
+   * its full-scale screen after signing in, with the choices carried over.
+   */
+  LandingGate = 'landing-gate',
 
   ResourceLayer = 'resource-layer',
   ResourceResults = 'resource-results',
@@ -99,6 +104,9 @@ export const SKILL_ORDER: Record<ViableSkill, number> = {
   [ViableSkill.FormFeedback]: 51,
   [ViableSkill.StoreAccess]: 52,
   [ViableSkill.ViewModelNaming]: 55,
+  // After the frontend rules it builds on (entrypoints, nav, shadcn, form feedback, the store), and
+  // before the backend block — it is only ever carried by analysis and frontend personas.
+  [ViableSkill.LandingGate]: 56,
   [ViableSkill.ResourceLayer]: 60,
   [ViableSkill.ResourceResults]: 62,
   [ViableSkill.ResourceMigrations]: 64,