💬 feat: Conversation Starters for Model Specs

[mharveybu]

Summary

Model specs defined in librechat.yaml currently have no way to offer conversation starters — only database agents/assistants do. Deployments that present curated specs as "agents" (preset + instructions + MCP servers) can't surface suggested prompts on the landing page; the closest workaround is HTML links in the spec description (via #13662), which open in a new tab and clutter the model selector.

This PR adds an optional conversation_starters field to model specs. When the active conversation uses a spec that defines starters, the chat landing renders clickable starter cards between the landing content and the chat input, and clicking one submits it as the first message — mirroring agent/assistant starters.

modelSpecs:
  list:
    - name: 'library-search'
      label: 'Library Search'
      conversation_starters:
        - 'Find books about machine learning'
        - 'Help me track down a citation'
      preset:
        endpoint: 'anthropic'
        model: 'claude-haiku-4-5'

Changes:

• packages/data-provider/src/models.ts: add conversation_starters?: string[] to TModelSpec and tModelSpecSchema (required so the field survives configSchema.strict() parsing in loadCustomConfig).
• client/src/components/Chat/Input/ConversationStarters.tsx: resolve the active spec via getModelSpec (same pattern as Landing.tsx) and fall back to its starters. Entity (agent/assistant) starters keep precedence; the MAX_CONVO_STARTERS cap is unchanged. Starter cards are refined: centered text, content-based width, word-boundary wrapping (replaces break-all), staggered fade-in, and a focus-visible ring.
• client/src/components/Chat/ChatView.tsx: render starters between the landing content and the chat input rather than below the input (footer slot).
• packages/api/src/modelSpecs/modelSpecs.test.ts: unit test asserting sanitizeModelSpecs preserves the new field while still stripping private preset fields.
• e2e/config/librechat.e2e.yaml + e2e/specs/mock/model-spec-starters.spec.ts: mock spec (5 starters) and Playwright coverage for rendering, absence on specs without starters, click-to-submit, and the 4-starter cap (mirrors model-spec-branding.spec.ts).

The yaml strings are intentionally uncapped in the zod schema: a .max() violation would fail the strict config parse and drop all model specs; the UI's 2-line clamp handles long text gracefully.

Related work: #11326 adds builder-UI conversation starters for database agents — complementary data source (DB agents vs. yaml specs); both touch the shared landing component, so whichever merges second needs a small rebase.

Change Type

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Testing

• npx playwright test --config=e2e/playwright.config.mock.ts model-spec-starters — 3/3 passed (rendering, absence, click-to-submit + cap)
• client: npm run test:ci — 204 suites / 2,526 tests passed; tsc --noEmit clean
• packages/api: npx jest src/modelSpecs — 7/7 passed (incl. new sanitize test)
• npm run build:data-provider succeeds; ESLint/Prettier clean on touched files
• Manual: ran backend + built client locally with a librechat.yaml defining starters on two specs; verified cards render on the landing for the active spec, clicking submits the prompt, and specs without starters show the unchanged landing

Test Configuration:

• Node v22, MongoDB 8 (Docker), librechat.yaml with modelSpecs.list[*].conversation_starters as in the example above

Checklist

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective or that my feature works
• Local unit tests pass with my changes
• A pull request for updating the documentation has been submitted: 📋 docs: Add conversation_starters to Model Specs object structure LibreChat-AI/librechat.ai#606

Closes

• Closes Enhancement: ability to set conversation starters #3619 — "Enhancement: ability to set conversation starters" requested starters for modelSpec "agents"; this PR provides that via the conversation_starters field in librechat.yaml. (The prompt-library integration suggested there could build on this as a follow-up.)
• Related (not closed): Enhancement: Extension of prompt library features to Librechat agent conversation starters #5053 — extending prompt-library features (fill-ins, versioning, auto-send toggles) to conversation starters is out of scope here but composes with this field.

🤖 Generated with Claude Code

[danny-avila]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🎉

Reviewed commit: 9e68d8633b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".