md / tools / assistant / README.md
Molino⺢Pro

README

Master Codebase Guidebook
Markdown + HTML Dev-Docs Renderer - Frontend Client Module

Default Index
Open README.md
Root: README.mdassistant
Milestones
⬆ Parent folder📁 archive📁 skills📝 README📝 README_
H1Assistant PRD - Molino App

version: 2026.04 status: active owner: Molino scope: assistant / AI / prompts last_updated: 2026-04-26

H2Focus Strip
NowLockDo Not BreakNext Closure
Keep AI assistivesuggestions, threads, structured modesno silent domain mutationunify idea generation through shared OpenAI wrapper
StateMeaning
built/lockedgetOpenAI(), runLLM(), runStructured(), Idea trace records
built/partialassistant threads, mode registry, structured mode guard
docs-aheadmode catalog split and unified OpenAI execution path
H10. Implementation Snapshot
H2Current goal
H3Keep Assistant as the AI orchestration layer

Use it for prompts, personas, threads, contexts, and generated artifacts.

H2Remaining features
H3Keep generated output traceable and non-authoritative

Generated output should not become canonical truth.

H3Separate prompt orchestration from domain mutations

Keep generation logic away from direct business writes.

H3Preserve explicit context and persona records

Make AI context visible and auditable.

H3Ensure generation routes create suggestions or derived files, not silent domain truth changes

Keep generated artifacts assistive rather than authoritative.

H2Next build steps
H3Inspect `app/api/ai/*`, `app/api/devprompts/route.ts`, and `app/ideas/api/generate/route.ts`

Check the orchestration paths first.

H3Verify assistant outputs reference source context where possible

Keep output traceable to its origin.

H3Keep direct domain writes out of prompt routes unless explicitly mediated by a domain action

Protect domain authority from silent writes.

H3Test generated output paths for typed, auditable results

Confirm the output remains typed and reviewable.

H2Prompt starter summary
  • Orchestrate prompts, personas, contexts, threads, and generated artifacts without mutating canonical records.
H2Prompt starter
Implement the next Assistant PRD slice. Use _PRD/tools/assistant/README.md as source of truth. Treat Assistant as orchestration for prompts, personas, contexts, threads, and generated artifacts. Generated output is assistive and traceable; it must not silently mutate canonical domain records. Keep prompt orchestration separate from domain truth. Inspect app/api/ai/*, app/api/devprompts/route.ts, app/ideas/api/generate/route.ts, idea repo/service files, and assistant-related Prisma models before editing.
H21. Product Identity
H3Name

Assistant

H3One-line Definition

Assistant is the AI orchestration layer for personas, prompts, threads, and generated output inside Molino.

H3User-facing Purpose

This feature exists so users can:

  • generate or refine structured content
  • interact with assistant workflows
  • capture guided AI output for follow-up actions
H3Internal Platform Purpose

Inside Molino App, this feature exists to:

  • keep AI context explicit and auditable
  • separate prompt orchestration from domain truth
  • support generation flows without turning AI into the source of truth
H22. Scope
H3In Scope
  • routes and APIs: app/api/ai/*, app/api/devprompts/route.ts, app/ideas/api/generate/route.ts
  • models: AssistantThread, AssistantMessage, AssistantFile, DevPromptThread, DevPromptMessage, DevPrompt, AIContext, AIPersona, GeneratedFile
  • helper surfaces for prompt, persona, and generation flows
H3Out of Scope
  • making AI output authoritative over canonical records
  • embedding business truth inside prompts
H23. Authority Model
  • assistant outputs are assistive artifacts
  • canonical data still lives in Prisma-backed domain models
  • generation routes may create derived files or suggestions, not silent truth changes
H24. Current Implementation Surface
  • app/api/ai/personas/route.ts
  • app/api/ai/contexts/route.ts
  • app/api/devprompts/route.ts
  • app/ideas/api/generate/route.ts
  • app/ideas/idea.repo.ts
  • app/ideas/idea.service.ts
  • app/assistant/actions/generateIdea.ts
  • app/assistant/lib/openai.ts
  • app/assistant/modes/modeRegistry.ts
  • app/assistant/modes/structured/runStructuredMode.ts
  • app/trips/new/actions/tripPlanner.ai.actions.ts
  • assistant-related Prisma models in prisma/schema.prisma
H24.1 Current Code Reality
H3Idea generation flow

app/ideas/api/generate/route.ts calls generateIdeaAction(), which builds a prompt from optional context, field, and user request. IdeaService.generateIdea() creates an Idea record before the model call, calls OpenAI, then saves the response back to the same Idea record.

This is traceable assistant output. It should remain a suggestion layer and must not silently mutate the referenced entity, entityId, or field.

H3OpenAI wrapper

app/assistant/lib/openai.ts owns the OpenAI client and two execution helpers:

  • runLLM() uses the Responses API and returns { output }.
  • runStructured() uses structured parsing, then falls back to runLLM() if parsing fails.
H3Mode registry

MODE_REGISTRY currently combines UI metadata, capability policy, visibility, execution style, and confirmation requirements. It is valuable, but it is doing multiple jobs. Any future catalog split should preserve the current registry behavior before moving lifecycle metadata elsewhere.

H3Trip planner assistant

planTripWithAssistant() uses structured output and explicitly forbids creating bookings, offers, orders, or documents. This is the correct pattern for assistant-to-domain boundaries: return intent first, then let domain actions decide what can be written.

H24.2 Code Audit - 2026-04-26
H3Built / locked
  • getOpenAI() centralizes OpenAI client creation and fails fast when OPENAI_API_KEY is missing.
  • runLLM() and runStructured() centralize Responses API and structured-output calls.
  • IdeaService.generateIdea() stores the prompt and generated response in Idea records without mutating the referenced domain entity.
  • MODE_REGISTRY records capabilities, visibility, execution style, and confirmation requirements per mode.
H3Built / partial
  • Assistant threads can be created and listed through app/api/assistant/threads/route.ts for the logged-in user.
  • generateIdeaAction() builds a clean text prompt from context, field, and user request.
  • runStructuredMode() enforces structured-mode execution by checking the mode policy.
H3Docs-ahead / pending
  • Assistant route docs should include app/api/assistant/threads/route.ts as an active thread surface.
  • Mode catalog separation is discussed in code comments but not yet implemented as a completed architecture split.
  • Idea generation still uses chat completions directly instead of the shared runLLM() wrapper, so OpenAI execution is not fully unified.
H3Critical next step

Keep Assistant behind commercial work. When touched, unify idea generation through the shared OpenAI wrapper and keep every generated result as an auditable suggestion, not a domain mutation.

H25. Acceptance Criteria
  • assistant routes stay isolated from core entity authority
  • generated output remains traceable
  • prompt and context changes do not mutate domain truth directly
H26. Locked Summary

Assistant is Molino's AI support layer. It may generate, suggest, and assist, but it must not replace canonical module authority.