@owlmeans/viable-common 0.0.24 → 0.0.26

package/src/connect/references.ts

@@ -5,12 +5,13 @@ import { connect } from './consts.js'
 import type { ConnectOp, ConnectOpResult } from './ops.js'
 import type { ConverterProjectLlmBody } from '../convert/index.js'
 import type {
-  ConnectAttachBody, ConnectCapabilitiesView, ConnectConfirmBody, ConnectCreateBody, ConnectJob,
-  ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectInquiryAnswerBody, ConnectJobParams,
+  ConnectAttachBody, ConnectCapabilitiesView, ConnectConfirmBody, ConnectCreateBody,
+  ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectInquiryAnswerBody,
   ConnectModifyBody, ConnectOpSubmission, ConnectPipelineParams, ConnectPipelineResumeBody,
-  ConnectPipelineState, ConnectProjectLlmBody, ConnectProjectSettings, ConnectProjectStatus,
-  ConnectProjectSummary, ConnectSessionOpen, ConnectSessionParams, ConnectSessionView,
-  ConnectWaitQuery, ConversionStatusView, ConvertCheck,
+  ConnectPipelineState, ConnectProjectBranding, ConnectProjectBrandingSave, ConnectProjectLlmBody,
+  ConnectProjectSettings, ConnectProjectStatus, ConnectProjectSummary, ConnectPullQuery,
+  ConnectSessionOpen, ConnectSessionParams, ConnectSessionView, ConnectStoryStatus,
+  ConversionStatusView, ConvertCheck,
 } from './types.js'
 
 type ConnectReference<Request extends RequestShape, Response> =
@@ -26,39 +27,47 @@ export interface ConnectReferences {
     close: ConnectReference<{ params: ConnectSessionParams }, ConnectSessionView>
   }
   op: {
-    pull: ConnectReference<{ params: ConnectSessionParams, query: ConnectWaitQuery }, ConnectOp[]>
+    pull: ConnectReference<{ params: ConnectSessionParams, query: ConnectPullQuery }, ConnectOp[]>
     submit: ConnectReference<{
       params: { sessionId: string, opId: string }, body: ConnectOpResult
     }, ConnectOpSubmission>
   }
   project: {
-    create: ConnectReference<{ body: ConnectCreateBody }, ConnectJob>
-    confirm: ConnectReference<{ params: { id: string }, body: ConnectConfirmBody }, ConnectJob>
+    create: ConnectReference<{ body: ConnectCreateBody }, ConnectProjectStatus>
+    confirm: ConnectReference<{ params: { id: string }, body: ConnectConfirmBody }, ConnectProjectStatus>
     list: ConnectReference<{}, ConnectProjectSummary[]>
     status: ConnectReference<{ params: { id: string } }, ConnectProjectStatus>
     attach: ConnectReference<{ body: ConnectAttachBody }, ConnectProjectStatus>
-    reinit: ConnectReference<{ params: { id: string } }, ConnectJob>
-    modify: ConnectReference<{ params: { id: string }, body: ConnectModifyBody }, ConnectJob>
+    reinit: ConnectReference<{ params: { id: string } }, ConnectProjectStatus>
+    modify: ConnectReference<{ params: { id: string }, body: ConnectModifyBody }, ConnectProjectStatus>
     settings: ConnectReference<{ params: { id: string } }, ConnectProjectSettings>
     llm: ConnectReference<{ params: { id: string }, body: ConnectProjectLlmBody }, ConnectProjectSettings>
     converterLlm: ConnectReference<{
       params: { id: string }, body: ConverterProjectLlmBody
     }, ConnectProjectSettings>
-    job: ConnectReference<{ params: ConnectJobParams, query: ConnectWaitQuery }, ConnectJob>
+    branding: {
+      get: ConnectReference<{ params: { id: string } }, ConnectProjectBranding>
+      save: ConnectReference<{
+        params: { id: string }, body: ConnectProjectBrandingSave
+      }, ConnectProjectBranding>
+    }
+  }
+  story: {
+    status: ConnectReference<{ params: { id: string, storyId: string } }, ConnectStoryStatus>
   }
   files: {
     list: ConnectReference<{ params: { id: string } }, string[]>
   }
   convert: {
-    create: ConnectReference<{ body: ConnectConvertCreateBody }, ConnectJob>
+    create: ConnectReference<{ body: ConnectConvertCreateBody }, ConversionStatusView>
     check: ConnectReference<{ params: { id: string } }, ConvertCheck>
-    start: ConnectReference<{ params: { id: string } }, ConnectJob>
+    start: ConnectReference<{ params: { id: string } }, ConversionStatusView>
     proceed: ConnectReference<{
       params: { id: string }, body: ConnectConvertProceedBody
-    }, ConnectJob>
-    cancel: ConnectReference<{ params: { id: string } }, ConnectJob>
+    }, ConversionStatusView>
+    cancel: ConnectReference<{ params: { id: string } }, ConversionStatusView>
     status: ConnectReference<{ params: { id: string } }, ConversionStatusView>
-    purge: ConnectReference<{ params: { id: string } }, ConnectJob>
+    purge: ConnectReference<{ params: { id: string } }, ConversionStatusView>
   }
   inquiry: {
     answer: ConnectReference<{
@@ -69,7 +78,7 @@ export interface ConnectReferences {
     state: ConnectReference<{ params: ConnectPipelineParams }, ConnectPipelineState>
     resume: ConnectReference<{
       params: ConnectPipelineParams, body: ConnectPipelineResumeBody
-    }, ConnectJob>
+    }, ConnectPipelineState>
   }
 }
 
@@ -88,19 +97,19 @@ export const connectRef: ConnectReferences = {
     close: entrypointRef<{ params: ConnectSessionParams }, ConnectSessionView>(connect.session.close),
   },
   op: {
-    pull: entrypointRef<{ params: ConnectSessionParams, query: ConnectWaitQuery }, ConnectOp[]>(connect.op.pull),
+    pull: entrypointRef<{ params: ConnectSessionParams, query: ConnectPullQuery }, ConnectOp[]>(connect.op.pull),
     submit: entrypointRef<{
       params: { sessionId: string, opId: string }, body: ConnectOpResult
     }, ConnectOpSubmission>(connect.op.submit),
   },
   project: {
-    create: entrypointRef<{ body: ConnectCreateBody }, ConnectJob>(connect.project.create),
-    confirm: entrypointRef<{ params: { id: string }, body: ConnectConfirmBody }, ConnectJob>(connect.project.confirm),
+    create: entrypointRef<{ body: ConnectCreateBody }, ConnectProjectStatus>(connect.project.create),
+    confirm: entrypointRef<{ params: { id: string }, body: ConnectConfirmBody }, ConnectProjectStatus>(connect.project.confirm),
     list: entrypointRef<{}, ConnectProjectSummary[]>(connect.project.list),
     status: entrypointRef<{ params: { id: string } }, ConnectProjectStatus>(connect.project.status),
     attach: entrypointRef<{ body: ConnectAttachBody }, ConnectProjectStatus>(connect.project.attach),
-    reinit: entrypointRef<{ params: { id: string } }, ConnectJob>(connect.project.reinit),
-    modify: entrypointRef<{ params: { id: string }, body: ConnectModifyBody }, ConnectJob>(connect.project.modify),
+    reinit: entrypointRef<{ params: { id: string } }, ConnectProjectStatus>(connect.project.reinit),
+    modify: entrypointRef<{ params: { id: string }, body: ConnectModifyBody }, ConnectProjectStatus>(connect.project.modify),
     settings: entrypointRef<{ params: { id: string } }, ConnectProjectSettings>(connect.project.settings),
     llm: entrypointRef<{
       params: { id: string }, body: ConnectProjectLlmBody
@@ -108,20 +117,30 @@ export const connectRef: ConnectReferences = {
     converterLlm: entrypointRef<{
       params: { id: string }, body: ConverterProjectLlmBody
     }, ConnectProjectSettings>(connect.project.converterLlm),
-    job: entrypointRef<{ params: ConnectJobParams, query: ConnectWaitQuery }, ConnectJob>(connect.project.job),
+    branding: {
+      get: entrypointRef<{ params: { id: string } }, ConnectProjectBranding>(connect.project.branding.get),
+      save: entrypointRef<{
+        params: { id: string }, body: ConnectProjectBrandingSave
+      }, ConnectProjectBranding>(connect.project.branding.save),
+    },
+  },
+  story: {
+    status: entrypointRef<{
+      params: { id: string, storyId: string }
+    }, ConnectStoryStatus>(connect.story.status),
   },
   convert: {
-    create: entrypointRef<{ body: ConnectConvertCreateBody }, ConnectJob>(connect.convert.create),
+    create: entrypointRef<{ body: ConnectConvertCreateBody }, ConversionStatusView>(connect.convert.create),
     check: entrypointRef<{ params: { id: string } }, ConvertCheck>(connect.convert.check),
-    start: entrypointRef<{ params: { id: string } }, ConnectJob>(connect.convert.start),
+    start: entrypointRef<{ params: { id: string } }, ConversionStatusView>(connect.convert.start),
     proceed: entrypointRef<{
       params: { id: string }, body: ConnectConvertProceedBody
-    }, ConnectJob>(connect.convert.proceed),
-    cancel: entrypointRef<{ params: { id: string } }, ConnectJob>(connect.convert.cancel),
+    }, ConversionStatusView>(connect.convert.proceed),
+    cancel: entrypointRef<{ params: { id: string } }, ConversionStatusView>(connect.convert.cancel),
     status: entrypointRef<{
       params: { id: string }
     }, ConversionStatusView>(connect.convert.status),
-    purge: entrypointRef<{ params: { id: string } }, ConnectJob>(connect.convert.purge),
+    purge: entrypointRef<{ params: { id: string } }, ConversionStatusView>(connect.convert.purge),
   },
   inquiry: {
     answer: entrypointRef<{
@@ -135,6 +154,6 @@ export const connectRef: ConnectReferences = {
     state: entrypointRef<{ params: ConnectPipelineParams }, ConnectPipelineState>(connect.pipeline.state),
     resume: entrypointRef<{
       params: ConnectPipelineParams, body: ConnectPipelineResumeBody
-    }, ConnectJob>(connect.pipeline.resume),
+    }, ConnectPipelineState>(connect.pipeline.resume),
   },
 }

package/src/connect/schemas.ts

@@ -1,15 +1,17 @@
 import type { JSONSchemaType } from 'ajv'
 import { ConversionDecision, OriginKind } from '../convert/consts.js'
 import {
-  CONNECT_INQUIRY_MAX_TEXT, ConnectHarness, ConnectLlm, ConnectOpErrorKind, ConnectSessionStatus,
-  ConnectTarget, ConnectTransport, ModelTaskResultKind, ModelTier
+  CONNECT_BRANDING_COPYRIGHT_MAX, CONNECT_BRANDING_GOOGLE_TAG_MAX,
+  CONNECT_BRANDING_ORGANIZATION_MAX, CONNECT_BRANDING_URL_MAX, CONNECT_INQUIRY_MAX_TEXT,
+  ConnectHarness, ConnectLlm, ConnectOpErrorKind, ConnectSessionStatus, ConnectTarget,
+  ConnectTransport, ModelTaskResultKind, ModelTier
 } from './consts.js'
 import type { ConnectOpResult, InquiryAnswerPayload } from './ops.js'
 import type {
   ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody,
-  ConnectCreateBody, ConnectJobParams, ConnectLlmBody, ConnectModifyBody, ConnectPipelineParams,
-  ConnectPipelineResumeBody, ConnectProjectLlmBody, ConnectSession, ConnectSessionOpen,
-  ConnectSessionParams, ConnectWaitQuery
+  ConnectCreateBody, ConnectLlmBody, ConnectModifyBody, ConnectPipelineParams,
+  ConnectPipelineResumeBody, ConnectProjectBrandingSave, ConnectProjectLlmBody, ConnectSession,
+  ConnectSessionOpen, ConnectPullQuery, ConnectSessionParams
 } from './types.js'
 
 /**
@@ -140,12 +142,12 @@ export const ConnectOpResultSchema = {
   additionalProperties: false,
 } as unknown as JSONSchemaType<ConnectOpResult>
 
-export const ConnectWaitQuerySchema = {
+export const ConnectPullQuerySchema = {
   type: 'object',
   properties: { wait: { type: 'integer', minimum: 0, maximum: 45, nullable: true } },
   required: [],
   additionalProperties: false,
-} as JSONSchemaType<ConnectWaitQuery>
+} as JSONSchemaType<ConnectPullQuery>
 
 /** Every project-scoped connector route addresses the project by `:id`. */
 export const ConnectProjectIdSchema = {
@@ -162,12 +164,12 @@ export const ConnectOpParamsSchema = {
   additionalProperties: false,
 } as JSONSchemaType<{ sessionId: string, opId: string }>
 
-export const ConnectJobParamsSchema = {
+export const ConnectStoryParamsSchema = {
   type: 'object',
-  properties: { id: idValue, jobId: { type: 'string', minLength: 1, maxLength: 256 } },
-  required: ['id', 'jobId'],
+  properties: { id: idValue, storyId: idValue },
+  required: ['id', 'storyId'],
   additionalProperties: false,
-} as JSONSchemaType<ConnectJobParams>
+} as JSONSchemaType<{ id: string, storyId: string }>
 
 export const ConnectCreateBodySchema = {
   type: 'object',
@@ -313,6 +315,33 @@ export const ConnectProjectLlmBodySchema = {
   additionalProperties: false,
 } as unknown as JSONSchemaType<ConnectProjectLlmBody>
 
+/**
+ * The branding patch a connector saves.
+ *
+ * STRUCTURAL only — lengths and types. What makes a value acceptable (a non-empty copyright and
+ * organization, a legal link that is `https://` or a same-origin path, a real Google tag id) is the
+ * platform's rule, applied by the handler to the MERGED record with the same checks the web form
+ * uses; a pattern repeated here would be a second copy of those rules free to drift from the first.
+ * No `pattern`, and no `enum` on the tag: a connector and the platform deploy apart, and a tag kind
+ * Google adds later must be refused by the rule that knows about it, not by a stale wire schema.
+ */
+export const ConnectProjectBrandingSaveSchema = {
+  type: 'object',
+  properties: {
+    copyright: {
+      type: 'string', minLength: 1, maxLength: CONNECT_BRANDING_COPYRIGHT_MAX, nullable: true,
+    },
+    organizationName: {
+      type: 'string', minLength: 1, maxLength: CONNECT_BRANDING_ORGANIZATION_MAX, nullable: true,
+    },
+    termsUrl: { type: 'string', maxLength: CONNECT_BRANDING_URL_MAX, nullable: true },
+    privacyUrl: { type: 'string', maxLength: CONNECT_BRANDING_URL_MAX, nullable: true },
+    googleTag: { type: 'string', maxLength: CONNECT_BRANDING_GOOGLE_TAG_MAX, nullable: true },
+  },
+  required: [],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<ConnectProjectBrandingSave>
+
 export const ModelTaskResultSchema = {
   type: 'object',
   properties: {

package/src/connect/types.ts

@@ -4,8 +4,8 @@ import type {
   OriginState, StoryEstimateBand
 } from '../convert/index.js'
 import type {
-  ConnectExecutor, ConnectHarness, ConnectJobBlock, ConnectJobKind, ConnectJobStatus, ConnectLlm,
-  ConnectSessionStatus, ConnectTarget, ConnectTransport, ModelTier
+  ConnectExecutor, ConnectHarness, ConnectLlm, ConnectSessionStatus, ConnectTarget,
+  ConnectTransport, ConnectWaitReason, ModelTier
 } from './consts.js'
 import type { InquiryAnswerPayload, InquiryPayload } from './ops.js'
 
@@ -82,68 +82,22 @@ export interface ConnectSessionView {
   expiresAt: string
 }
 
-/**
- * A derived view of "what the platform is doing for this project right now".
- *
- * Never stored. It is composed per request from the project lock, the slot record, the story
- * card, the latest pipeline run row and the operations queued for the project — the same facts
- * the manager UI reads, arranged for a caller that has one question ("may I stop waiting?") and
- * one follow-up ("what do I call next?").
- *
- * Its `id` is composed and parsed only through `jobIdOf` / `parseJobId`.
- */
-export interface ConnectJob {
-  id: string
-  kind: ConnectJobKind
-  status: ConnectJobStatus
-  /** The project CARD id. */
-  projectId: string
-  /**
-   * The story CARD id — never the story's code.
-   *
-   * The name is kept because a parent agent reads it: a wire field name is that agent's
-   * vocabulary and is never renamed, only re-documented.
-   */
-  storyId?: string
-  runId?: string
-  /** The pipeline step in flight, when a run row says. */
-  phase?: string
-  progress?: ConnectJobProgress
-  blockedOn?: ConnectJobBlock
-  /**
-   * The question a parked run is waiting on — present exactly when it is blocked on one.
-   *
-   * Carried on the job rather than left to a second lookup because a parent reads a job and
-   * nothing else while it polls: a run that stopped for a person, described only as "blocked",
-   * is a run whose parent waits out the timeout for a question it was never shown. It is also
-   * the ONLY way back to a question whose operation timed out while nobody was attached — the
-   * connector's own queue holds nothing at that point.
-   */
-  inquiry?: InquiryPayload
-  /** One sentence a parent agent can show a human. */
-  message?: string
-  /** Present on `Failed`, and on `Done` where the run recorded a warning. */
-  error?: string
-  /** Kind-specific payload once `Done`. */
-  result?: Record<string, unknown>
-  startedAt?: string
-  updatedAt: string
+export interface ConnectPullQuery {
+  /** Seconds to wait before answering; clamped to the pull ceiling. */
+  wait?: number
 }
 
-export interface ConnectJobProgress {
+export interface ConnectRunStatus {
+  runId: string
+  pipeline: string
+  status: string
   step?: string
   completed: string[]
   pending: string[]
-}
-
-export interface ConnectJobParams {
-  id: string
-  jobId: string
-}
-
-export interface ConnectWaitQuery {
-  /** Seconds to wait before answering; clamped to the pull ceiling. */
-  wait?: number
+  warnings?: string[]
+  error?: string
+  startedAt?: string
+  updatedAt?: string
 }
 
 /** What a connector needs to know about a project in one call. */
@@ -181,18 +135,30 @@ export interface ConnectProjectStatus {
   }
   production?: { id: string, status: string, host?: string }
   agent: { locked: boolean, task?: string, lockedAt?: string }
-  run?: {
-    runId: string
-    pipeline: string
-    status: string
-    step?: string
-    completed: string[]
-    pending: string[]
-    error?: string
-  }
+  run?: ConnectRunStatus
+  waitingFor?: ConnectWaitReason
+  pendingInquiry?: InquiryPayload
   session?: ConnectSessionView
   /** Set for a local target: the connector should not offer cloud-only operations. */
   local: boolean
+  updatedAt: string
+}
+
+/** A story card composed with its deterministic development run. */
+export interface ConnectStoryStatus {
+  projectId: string
+  story: {
+    id: string
+    code: string
+    title: string
+    status: string
+    intrinsic: string
+    warning?: string
+  }
+  run?: ConnectRunStatus
+  waitingFor?: ConnectWaitReason
+  pendingInquiry?: InquiryPayload
+  updatedAt: string
 }
 
 /** The record a local project keeps so a later session knows what it is. */
@@ -217,7 +183,7 @@ export interface ConnectProfileSettingsView extends ConnectProfileSettings {
    * The profile's preference for who performs a CONVERSION's model calls.
    *
    * Its own setting rather than a reading of `llmMode`, because the two answer for different
-   * work: a conversion reads somebody else's whole repository, which is the one job where handing
+   * work: a conversion reads somebody else's whole repository, which is the one case where handing
    * the inference to the parent agent is the cheap default rather than the experimental option.
    *
    * OPTIONAL for the same reason {@link ConnectCapabilitiesView.defaults} carries `converterLlm`
@@ -257,6 +223,34 @@ export interface ConnectProjectLlmBody {
   llmMode: ConnectLlm | null
 }
 
+/**
+ * A project's branding as a connector reads it — what the generated application says about who
+ * made it, and the Google tag it loads.
+ *
+ * Every field is a string, `''` when unset, in the platform's own branding vocabulary. The
+ * platform credit is absent on purpose: hiding it is a paid capability behind its own gated route,
+ * and neither reading nor saving this record may reach it.
+ */
+export interface ConnectProjectBranding {
+  /** The copyright line in the application's footer. Never empty once saved. */
+  copyright: string
+  /** The organization's display name. Never empty once saved. */
+  organizationName: string
+  /** `''`, an `https://` URL, or a same-origin path such as `/terms` (the generated page). */
+  termsUrl: string
+  /** `''`, an `https://` URL, or a same-origin path such as `/privacy` (the generated page). */
+  privacyUrl: string
+  /** `''`, or a Google tag id: `GTM-…`, `G-…`, `GT-…`, `AW-…`, `DC-…`. */
+  googleTag: string
+}
+
+/**
+ * A PATCH of a project's branding: every field optional, and an absent field keeps its current
+ * value. The platform merges it over what is stored, validates the result as a whole with the
+ * rules the web form uses, and answers the merged record.
+ */
+export interface ConnectProjectBrandingSave extends Partial<ConnectProjectBranding> {}
+
 /** What the platform tells a connector about itself. */
 export interface ConnectCapabilitiesView {
   /** Tier → the platform role names that will be asked for at that tier. */
@@ -397,6 +391,7 @@ export interface ConversionStatusView {
   runId?: string
   /** Set exactly when `status` is `Waiting`: the question the run stopped on. */
   pendingInquiry?: InquiryPayload
+  waitingFor?: ConnectWaitReason
   lastError?: string
   updatedAt: string
 }
@@ -428,6 +423,8 @@ export interface ConnectPipelineState {
   failedAt?: string
   error?: string
   note?: string
+  waitingFor?: ConnectWaitReason
+  pendingInquiry?: InquiryPayload
   attempts: number
   startedAt: string
   heartbeatAt: string

package/src/consts.ts

@@ -17,6 +17,9 @@ export const metadataConfigs = [
   'brandingPrivacyUrl',
   'brandingCredit',
   'brandingHideCreditIntent',
+  // Optional in `SlotConstMetadata`: omitted from a push while unset (an older publisher refuses
+  // an undeclared key), so an empty stored row must never be delivered as `''`.
+  'brandingGoogleTag',
 ] satisfies (keyof NonSecretScalarSlotMetadata)[]
 
 export const metadataLists = [

package/src/design/runtime.ts

@@ -40,7 +40,7 @@ export const isEphemeralActor = (actor?: StoryActor): boolean =>
 export interface StoryDesignJob {
   /** The queue it is enqueued onto. */
   queue: string
-  /** The job name, which IS its entrypoint alias — `app.job.<name>`. */
+  /** The job name, which becomes the backend-only `job:<name>` protocol alias. */
   name: string
   /** The processor module, relative to the worker package's `src`. */
   path: string

package/src/metadata/types.ts

@@ -116,6 +116,12 @@ export interface StoryMeta extends Record<string, unknown> {
    * that moves section when it is implemented leaves its own dashboard behind.
    */
   section?: string
+  /**
+   * This is the landing gate's story — a guest starts it on the landing page and continues here
+   * after signing in. Copied from the card's `fields.landing`; written only when `true`, so every
+   * other story's file keeps the shape it always had.
+   */
+  landing?: boolean
   entity: string
   entities: string[]
   screens: StoryScreenRef[]
@@ -153,6 +159,8 @@ export interface StoryWriteInput {
   narrative: string
   status: string
   primary: boolean
+  /** The card's landing flag — see {@link StoryMeta.landing}. Absent reads as `false`. */
+  landing?: boolean
   /** Carried through a develop run so the rewrite does not drop the scaffold's assignment. */
   section?: string
   /** Likewise the reserved screen name. */

package/src/planning/consts.ts

@@ -35,7 +35,7 @@ export const VIABLE_SPEC_FLOW = 'viable:spec'
  * The story flow's status keys.
  *
  * Byte-identical to the strings a story has always carried — the frontmatter of
- * `docs/stories/<code>.md`, the connector's job status mapping, the board's columns, their i18n
+ * `docs/stories/<code>.md`, connector status rendering, the board's columns, their i18n
  * keys and every end-to-end selector read these exact values. A key is a wire contract and is
  * never renamed.
  */

package/src/planning/helpers.ts

@@ -115,19 +115,22 @@ export const projectBriefOf = (project: Workcard, specs: readonly Specification[
  * What the metadata store writes to `docs/stories/<code>.md`, from the card and a run's content.
  *
  * The CODE is the target's only story identifier — a card id never reaches a target file — so a
- * story card without one is refused rather than filed under its id.
+ * story card without one is refused rather than filed under its id. The landing flag is carried
+ * only when it is set, so every other story's frontmatter keeps the shape it always had.
  */
 export const storyWriteInputOf = (card: Workcard, content: StoryWriteContent): StoryWriteInput => {
   if (card.code == null || card.code === '') {
     throw new ProjectStoryMissconfigured('no-code')
   }
   const { status, ...rest } = content
+  const fields = storyFieldsOf(card)
 
   return {
     ...rest,
     code: card.code,
     narrative: card.title,
     status: status ?? card.status,
-    primary: storyFieldsOf(card).primary,
+    primary: fields.primary,
+    ...(fields.landing === true ? { landing: true } : {}),
   }
 }

package/src/planning/index.ts

@@ -3,4 +3,5 @@ export * from './errors.js'
 export * from './schemas.js'
 export * from './flows.js'
 export * from './helpers.js'
+export * from './landing.js'
 export type * from './types.js'

package/src/planning/landing.ts

@@ -0,0 +1,43 @@
+import { TITLE_MAX } from '@owlmeans/planning'
+
+/**
+ * The sentence a landing story's narrative carries — what a person reading the board sees.
+ *
+ * The AUTHORITY is the card's `fields.landing` flag, never this text: the design and development
+ * stages key on the flag, and a person may reword the narrative at any time. The sentence exists so
+ * the board says in plain words why this story is different, and so the analyst and the designer,
+ * who read the narrative, write a screen that continues what the guest started.
+ *
+ * A constant, byte for byte, because {@link hasLandingSentence} is how a resumed decision step
+ * knows it already appended it.
+ */
+export const LANDING_STORY_SENTENCE = 'A visitor can start this on the landing page without an account;'
+  + ' after signing in they continue here with their choices carried over.'
+
+const normalized = (text: string): string => text.replace(/\s+/g, ' ')
+
+/** Whether a narrative already carries the landing sentence, whatever whitespace surrounds it. */
+export const hasLandingSentence = (title: string): boolean =>
+  normalized(title).includes(LANDING_STORY_SENTENCE)
+
+/**
+ * The narrative with the landing sentence appended once.
+ *
+ * Idempotent — a narrative that already carries the sentence comes back unchanged, so a decision
+ * step that is resumed after it wrote the card never appends a second copy. It never produces a
+ * title longer than a card accepts (`TITLE_MAX`): a narrative with no room left is returned as it
+ * is rather than cut, because a person's words are worth more than the note, and the flag on the
+ * card still carries the fact.
+ */
+export const withLandingSentence = (title: string): string => {
+  if (hasLandingSentence(title)) {
+    return title
+  }
+  const base = title.trimEnd()
+  if (base === '') {
+    return LANDING_STORY_SENTENCE
+  }
+  const joined = `${base} ${LANDING_STORY_SENTENCE}`
+
+  return joined.length > TITLE_MAX ? title : joined
+}

package/src/planning/schemas.ts

@@ -28,6 +28,18 @@ export const ViableProjectFieldsSchema = {
     origin: { ...ProjectOriginSchema, nullable: true },
     connectLlmMode: { type: 'string', enum: [...Object.values(ConnectLlm), null], nullable: true },
     converterLlmMode: { type: 'string', enum: [...Object.values(ConnectLlm), null], nullable: true },
+    // `story: null` is a DECIDED "no gate" and must stay spellable; an absent `landing` is "never
+    // decided". `at` carries no `format`: the planning registry compiles without ajv-formats.
+    landing: {
+      type: 'object',
+      nullable: true,
+      properties: {
+        story: { type: 'string', minLength: 1, maxLength: CODE_MAX, nullable: true },
+        at: { type: 'string', minLength: 1, maxLength: 32 },
+      },
+      required: ['at'],
+      additionalProperties: false,
+    },
   },
   required: [],
   additionalProperties: false,
@@ -48,6 +60,7 @@ export const ViableStoryFieldsSchema = {
     actor: { type: 'string', enum: [...Object.values(StoryActor), null], nullable: true },
     warning: { type: 'string', maxLength: 1024, nullable: true },
     kind: { type: 'string', enum: [...Object.values(StoryKind), null], nullable: true },
+    landing: { type: 'boolean', nullable: true },
   },
   required: ['area', 'primary'],
   additionalProperties: false,

package/src/planning/types.ts

@@ -32,6 +32,23 @@ export type ViableProjectFields = {
   connectLlmMode?: ConnectLlm
   /** Who performs a conversion's model calls on this project; absent inherits. */
   converterLlmMode?: ConnectLlm
+  /**
+   * The landing-gate decision: which story a guest can start on the landing page.
+   *
+   * Three states, and the third is why this is an object rather than a code: ABSENT means the
+   * decision was never made (an initialization that has not reached it, or a project older than
+   * the gate), `story: null` means it WAS made and the answer is "no gate", and a code names the
+   * story. A failed decision is never recorded — writing `null` for it would read as a decided
+   * "none" and no later run would ask again. `at` is when it was decided, an ISO timestamp.
+   */
+  landing?: ViableLandingDecision
+}
+
+/** The recorded landing-gate decision — see {@link ViableProjectFields.landing}. */
+export interface ViableLandingDecision {
+  /** The story card's CODE, or `null` for a decided "no gate". */
+  story: string | null
+  at: string
 }
 
 /**
@@ -51,6 +68,15 @@ export type ViableStoryFields = {
   warning?: string
   /** Which half of the analysis the story came from. */
   kind?: StoryKind
+  /**
+   * The story a guest starts on the landing page — the landing gate's story. At most one per
+   * project, and the project card's `fields.landing.story` names the same code.
+   *
+   * Its development gains a step that replaces the gate's sketch on the guest home with the real
+   * component, and its full-scale screen reads the choices the guest carried over. Absent and
+   * `false` read the same.
+   */
+  landing?: boolean
 }
 
 export interface ViableProjectCard extends Project {
@@ -67,9 +93,9 @@ export type ViableSpecification = Specification
 /**
  * What a develop run hands the metadata store beside the card.
  *
- * The code, the narrative and the primary flag are the CARD's and are never passed separately — a
- * second copy is a second answer. `status` defaults to the card's own.
+ * The code, the narrative, the primary flag and the landing flag are the CARD's and are never
+ * passed separately — a second copy is a second answer. `status` defaults to the card's own.
  */
 export type StoryWriteContent =
-  & Omit<StoryWriteInput, 'code' | 'narrative' | 'primary' | 'status'>
+  & Omit<StoryWriteInput, 'code' | 'narrative' | 'primary' | 'landing' | 'status'>
   & { status?: string }