feat(agent): teach agents the email sending workflow pattern

[larryro]

Summary

• Add workflow creation approval system with sub-agent delegation for creating workflows through chat
• Implement modular syntax reference system for workflow agent to retrieve documentation on-demand
• Document the conversation + approval pattern for sending emails from workflows
• Add UI components for workflow creation approvals in chat interface

Changes

Workflow Creation Approval System

• Add WorkflowCreationApprovalCard component for displaying workflow approvals in chat
• Add useWorkflowCreationApprovals hook to fetch workflow creation approvals per thread
• Integrate workflow creation approvals into chat interface alongside integration approvals
• Add workflow_assistant tool that delegates to a specialized Workflow Assistant Agent
• Add create_workflow_tool for defining workflow configurations
• Add create_workflow_approval for creating pending workflow approvals
• Add execute_approved_workflow_creation action to execute approved workflows
• Update approvals schema and validators for workflow_creation resource type

Modular Syntax Reference System

• Add syntax_reference.ts with categorized documentation (quick_start, common_patterns, trigger, llm, action, condition, loop, email, etc.)
• Add get_syntax_reference operation to workflow_examples tool
• Enhance tool descriptions with clearer JSON formatting rules
• Add category metadata to predefined workflows for better discovery
• Pass parentThreadId to sub-agents for approval linking
• Add validation helpers for LLM and action step configs

Email Workflow Documentation

• Add EMAIL SENDING PATTERN section to workflow_syntax_compact.ts with step-by-step instructions
• Add SENDING EMAILS FROM WORKFLOWS section to create_workflow_agent.ts with code examples
• Enhance conversation_action.ts description with email metadata documentation
• Add EMAIL WORKFLOWS section to create_chat_agent.ts for user inquiries

Other Changes

• Rename index_registry.ts to get_table_indexes.ts for clarity
• Refactor update_workflow_step_tool.ts to reduce code duplication

Test plan

• Verify workflow assistant sub-agent can create workflows through chat
• Verify workflow creation approvals appear in chat and can be approved/rejected
• Verify approved workflow creations execute successfully
• Verify workflow agent can retrieve syntax references by category
• Verify workflow agent can create email-sending workflows using the conversation + approval pattern
• Verify chat agent correctly explains the email workflow pattern when asked
• Verify no TypeScript errors in modified files

---

@coderabbitai full review

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Workflow creation approvals system with dedicated chat interface for approving or rejecting workflow creation requests.
  • Specialized workflow assistant tool consolidating all workflow operations through a single entry point.
  • Categorized workflow syntax reference documentation covering patterns, triggers, steps, and email workflows.

• Improvements

  • Enhanced workflow guidance and step-by-step instructions for creating and modifying workflows.
  • Updated default AI model to GPT-5.2 for improved coding capabilities.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds end-to-end workflow creation and approval functionality and a delegated workflow assistant: new Convex tools (create_workflow, workflow_assistant), tool registry entries, agent changes (delegation mode, required OPENAI_CODING_MODEL), workflow creation approval creation and execution mutations/actions, approval metadata/type additions, validation and schema updates, new workflow syntax/reference modules and instruction prompts, UI support for workflow creation approvals (hook, approval card, chat integration), execution path for approved workflow creation, and various validation/documentation text updates. Also updates .env.example coding model and built-in index handling for workflow processing records.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related issues

• feat(workflow-agent): add email sending pattern knowledge to workflow and chat agents #70: Implements the documented email-sending workflow pattern and related agent/instruction updates referenced by the issue.

Possibly related PRs

• tale-project/poc2#465: Overlaps on workflow agent and tooling changes (create_workflow_agent and workflow assistant additions).
• tale-project/poc2#354: Related to adding AI-driven workflow assistant tooling and agent delegation features.
• tale-project/poc2#440: Overlaps approval surface changes (schema/types/validators and approval-handling code).

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro (Legacy)

📥 Commits

Reviewing files that changed from the base of the PR and between 51c944d and b92a289.

📒 Files selected for processing (4)

• services/platform/convex/lib/create_chat_agent.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts

🧰 Additional context used

📓 Path-based instructions (3)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx}: USE implicit typing whenever possible in TypeScript
DO NOT use type casting. Avoid any, and unknown whenever possible in TypeScript

Files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/lib/create_chat_agent.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx,js,jsx}: ALWAYS put imports at the top and exports at the bottom. Keep them sorted correctly
PREFER named exports. AVOID default exports (only if needed)

Files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/lib/create_chat_agent.ts

**/convex/**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/convex/**/*.{ts,tsx}: CONSIDER TO use rate limiting and action caching in Convex
DO NOT use .collect(), use for await (const ... of ...) instead in Convex

Files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/lib/create_chat_agent.ts

🧠 Learnings (12)

📚 Learning: 2025-12-15T14:44:04.593Z

Learnt from: larryro
Repo: tale-project/tale PR: 18
File: services/platform/convex/workflow/actions/conversation/conversation_action.ts:47-98
Timestamp: 2025-12-15T14:44:04.593Z
Learning: In Convex action files under services/platform/convex/workflow/actions/**, prefer maintaining a separate TypeScript type for the action parameters alongside the runtime validators (parametersValidator). The TypeScript type provides IDE support and compile-time checking, while the validator handles runtime validation. Document this design with a clear comment next to the type/validator pair explaining the rationale (e.g., separate types for static typing vs runtime checks, and how they relate). This pattern applies across all actions in this directory, not just a single file.

Applied to files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts

📚 Learning: 2025-07-20T08:40:24.693Z

Learnt from: CR
Repo: talecorp/poc PR: 0
File: .cursor/rules/ai.mdc:0-0
Timestamp: 2025-07-20T08:40:24.693Z
Learning: Applies to **/actions/*.ts : For text generation, use the `generateObject` or similar functions from the AI SDK

Applied to files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts

📚 Learning: 2025-12-30T06:20:46.309Z

Learnt from: larryro
Repo: tale-project/tale PR: 37
File: services/platform/convex/model/conversations/validators.ts:106-139
Timestamp: 2025-12-30T06:20:46.309Z
Learning: In services/platform/convex/model/conversations/validators.ts, conversationItemValidator and conversationWithMessagesValidator are intentionally kept as separate validators despite having identical structures. This separation serves different semantic purposes: conversationItemValidator is for list responses while conversationWithMessagesValidator is for single conversation detail views. The duplication allows future divergence when list views might need different fields than detail views for performance or feature reasons.

Applied to files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts

📚 Learning: 2025-12-15T14:01:55.275Z

Learnt from: larryro
Repo: tale-project/tale PR: 18
File: services/platform/convex/workflow/actions/conversation/helpers/update_conversations.ts:7-10
Timestamp: 2025-12-15T14:01:55.275Z
Learning: In Convex action helpers (services/platform/convex/workflow/actions/**/helpers/*.ts), using Record<string, unknown> for update parameters is acceptable when field validation is handled at the mutation level in Convex. This provides flexibility for dynamic field updates while keeping validation centralized at the mutation layer.

Applied to files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts

📚 Learning: 2025-12-26T03:04:07.995Z

Learnt from: larryro
Repo: tale-project/tale PR: 35
File: services/platform/convex/approvals.ts:51-62
Timestamp: 2025-12-26T03:04:07.995Z
Learning: In Convex approvals API (services/platform/convex/approvals.ts), continue the pattern of maintaining separate internalQuery functions for internal vs public API access (e.g., getApprovalInternal vs getApprovalById) even if implementations are identical. This separation preserves the ability to diverge access control patterns in the future without breaking call sites. Apply this guideline broadly to the Convex-related API files under services/platform/convex/, using the pattern services/platform/convex/**/*.ts to cover similar modules. Ensure new or refactored internal/public wrappers follow this convention and document intent where access rules may evolve.

Applied to files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/lib/create_chat_agent.ts

📚 Learning: 2025-12-30T03:24:33.770Z

Learnt from: larryro
Repo: tale-project/tale PR: 36
File: services/platform/convex/wf_step_defs.ts:33-39
Timestamp: 2025-12-30T03:24:33.770Z
Learning: In Convex API files under services/platform/convex (e.g., wf_step_defs.ts and peers) refrain from delegating trivial single-line database calls like ctx.db.get(id) to model helpers. Use direct calls for simple operations with no extra business logic. Reserve model helpers for complex tasks (ordering, filtering, validation, transformation). This guideline applies to all .ts files in this Convex API area.

Applied to files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/lib/create_chat_agent.ts

📚 Learning: 2025-12-30T06:21:13.183Z

Learnt from: larryro
Repo: tale-project/tale PR: 37
File: services/platform/convex/model/documents/validators.ts:89-102
Timestamp: 2025-12-30T06:21:13.183Z
Learning: Do not flag a missing trailing newline for TypeScript files in code reviews. POSIX text files should end with a trailing newline and Prettier (or your formatter) will enforce this. Treat the trailing newline as a non-issue in reviews for all TS files.

Applied to files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/lib/create_chat_agent.ts

📚 Learning: 2025-12-15T14:44:09.823Z

Learnt from: larryro
Repo: tale-project/tale PR: 18
File: services/platform/convex/workflow/actions/conversation/conversation_action.ts:47-98
Timestamp: 2025-12-15T14:44:09.823Z
Learning: In Convex action files (services/platform/convex/workflow/actions/**/), maintaining a separate TypeScript type alongside the parametersValidator is an acceptable pattern when documented. The TypeScript type provides IDE support and compile-time checking, while the validator provides runtime validation. This intentional separation should be documented with a comment explaining the design choice.

Applied to files:

• services/platform/convex/lib/create_workflow_agent.ts

📚 Learning: 2025-12-30T03:53:06.120Z

Learnt from: larryro
Repo: tale-project/tale PR: 36
File: services/platform/convex/workflow_assistant_agent.ts:94-107
Timestamp: 2025-12-30T03:53:06.120Z
Learning: In services/platform/convex/workflow_assistant_agent.ts, using `any` type for step parameters during toonification (compact representation) is acceptable when step structures vary significantly by stepType (llm, condition, action, loop). The sanitization approach extracts only needed fields for context, and strict typing with complex discriminated unions would add maintenance burden without practical benefit since the data is only used for compact representation, not type-specific processing.

Applied to files:

• services/platform/convex/lib/create_workflow_agent.ts

📚 Learning: 2025-12-20T13:38:13.773Z

Learnt from: larryro
Repo: tale-project/tale PR: 30
File: services/platform/convex/model/chat_agent/chat_with_agent.ts:130-144
Timestamp: 2025-12-20T13:38:13.773Z
Learning: In services/platform/convex/model/chat_agent/chat_with_agent.ts, image fileIds are intentionally displayed as `*(fileId: ${attachment.fileId})*` in the markdown because the AI needs to reference them from thread history for re-analysis using the image tool. This is a business/developer tool, not consumer-facing, so technical metadata visibility is acceptable.

Applied to files:

• services/platform/convex/lib/create_chat_agent.ts

📚 Learning: 2025-12-16T07:35:54.411Z

Learnt from: larryro
Repo: tale-project/tale PR: 19
File: services/platform/convex/predefined_workflows/circuly_sync_products.ts:121-121
Timestamp: 2025-12-16T07:35:54.411Z
Learning: In predefined workflows (workflowType: 'predefined') where action steps return controlled, consistent data structures (e.g., query actions always returning data.items as an array, even if empty), verbose null-safety guards in JEXL condition expressions are not necessary and reduce readability. The simplified form like `steps.query_existing_product.output.data.items|length > 0` is preferred over verbose nested ternary operators when the data structure is known and guaranteed by the action implementation.

Applied to files:

• services/platform/convex/lib/create_chat_agent.ts

📚 Learning: 2025-12-16T07:35:53.543Z

Learnt from: larryro
Repo: tale-project/tale PR: 19
File: services/platform/convex/predefined_workflows/circuly_sync_subscriptions.ts:205-205
Timestamp: 2025-12-16T07:35:53.543Z
Learning: In predefined workflows with controlled data structures (e.g., services/platform/convex/predefined_workflows/*.ts), defensive null checks in JEXL expressions for property access are not required when the execution flow guarantees the data exists. For example, accessing `steps.X.output.data.items|length` after a successful fetch does not need conditional checks like `(data && data.items) ? data.items|length : 0` because the predefined workflow structure ensures data.items is present at that execution point.

Applied to files:

• services/platform/convex/lib/create_chat_agent.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build Docker Image

🔇 Additional comments (4)

services/platform/convex/workflow/workflow_syntax_compact.ts (1)

168-237: Comprehensive email workflow pattern documentation.

Excellent addition of detailed step-by-step guidance with working code examples. The structure is clear, the template variable usage is correct, and the distinction between required and optional metadata fields is well documented.

services/platform/convex/workflow/actions/conversation/conversation_action.ts (1)

111-123: Clear and actionable email workflow guidance.

The expanded description provides helpful context for workflows using the conversation action for outbound emails. The required vs optional metadata distinction is clear, and the reference to the predefined workflow example is useful.

services/platform/convex/lib/create_workflow_agent.ts (1)

405-456: Excellent workflow-specific email pattern documentation.

The "SENDING EMAILS FROM WORKFLOWS" section provides comprehensive guidance with well-structured code examples. The inclusion of the workflow_examples tool call syntax (line 455) is particularly helpful for agents learning the pattern. The examples correctly use template variables and match the action definitions.

services/platform/convex/lib/create_chat_agent.ts (1)

133-145: Verify the email workflow automation behavior and timing.

The documented pattern correctly identifies the metadata fields (emailSubject, emailBody, customerEmail), confirms the 'product_recommendation_email' predefined workflow exists, and accurately specifies resourceType 'conversations' for approval linking. However, the critical claim that "System auto-sends email when the approval is approved" requires clarification. The product_recommendation_email workflow uses a manual/scheduled trigger (not event-driven) and implements a polling pattern that finds approved approvals rather than triggering automatically on approval status changes. Confirm whether this polling mechanism or an additional event-driven handler provides the auto-send behavior described, and clarify the expected timing between approval and email sending.

[larryro]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[coderabbitai]

Actionable comments posted: 10

♻️ Duplicate comments (1)

services/platform/convex/workflow/workflow_syntax_compact.ts (1)

218-218: Consider abstracting implementation detail.

The mention of sendMessageViaEmail() exposes an internal function name. Consider whether implementation details should be included in user-facing documentation, as they may change independently of the public API pattern.

🔎 Proposed simplification

-- When user approves, system automatically sends the email via sendMessageViaEmail()
+- When user approves, system automatically sends the email

📜 Review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro (Legacy)

📥 Commits

Reviewing files that changed from the base of the PR and between e49f32c and 3e29410.

⛔ Files ignored due to path filters (1)

• services/platform/convex/_generated/api.d.ts is excluded by !**/_generated/**

📒 Files selected for processing (33)

• .env.example
• services/platform/app/(app)/dashboard/[id]/chat/components/chat-interface.tsx
• services/platform/app/(app)/dashboard/[id]/chat/components/workflow-creation-approval-card.tsx
• services/platform/app/(app)/dashboard/[id]/chat/hooks/use-workflow-creation-approvals.ts
• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/agent_tools/sub_agents/workflow_assistant_tool.ts
• services/platform/convex/agent_tools/tool_registry.ts
• services/platform/convex/agent_tools/workflows/create_workflow_approval.ts
• services/platform/convex/agent_tools/workflows/create_workflow_tool.ts
• services/platform/convex/agent_tools/workflows/execute_approved_workflow_creation.ts
• services/platform/convex/agent_tools/workflows/helpers/read_predefined_workflows.ts
• services/platform/convex/agent_tools/workflows/helpers/syntax_reference.ts
• services/platform/convex/agent_tools/workflows/save_workflow_definition_tool.ts
• services/platform/convex/agent_tools/workflows/update_workflow_step_tool.ts
• services/platform/convex/agent_tools/workflows/workflow_examples_tool.ts
• services/platform/convex/approvals.ts
• services/platform/convex/lib/create_chat_agent.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/model/approvals/link_approvals_to_message.ts
• services/platform/convex/model/approvals/types.ts
• services/platform/convex/model/approvals/validators.ts
• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/model/workflow_processing_records/index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/schema.ts
• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/workflow/helpers/validation/steps/action.ts
• services/platform/convex/workflow/helpers/validation/steps/llm.ts
• services/platform/convex/workflow/helpers/validation/validate_step_config.ts
• services/platform/convex/workflow/instructions/core_instructions.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts

🧰 Additional context used

📓 Path-based instructions (5)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx}: USE implicit typing whenever possible in TypeScript
DO NOT use type casting. Avoid any, and unknown whenever possible in TypeScript

Files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/model/approvals/validators.ts
• services/platform/convex/agent_tools/workflows/helpers/syntax_reference.ts
• services/platform/convex/schema.ts
• services/platform/convex/workflow/helpers/validation/validate_step_config.ts
• services/platform/convex/workflow/instructions/core_instructions.ts
• services/platform/convex/workflow/helpers/validation/steps/llm.ts
• services/platform/convex/model/approvals/types.ts
• services/platform/convex/agent_tools/sub_agents/workflow_assistant_tool.ts
• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/agent_tools/workflows/create_workflow_approval.ts
• services/platform/convex/agent_tools/tool_registry.ts
• services/platform/app/(app)/dashboard/[id]/chat/components/workflow-creation-approval-card.tsx
• services/platform/convex/agent_tools/workflows/helpers/read_predefined_workflows.ts
• services/platform/convex/agent_tools/workflows/update_workflow_step_tool.ts
• services/platform/app/(app)/dashboard/[id]/chat/components/chat-interface.tsx
• services/platform/convex/lib/create_chat_agent.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/agent_tools/workflows/create_workflow_tool.ts
• services/platform/app/(app)/dashboard/[id]/chat/hooks/use-workflow-creation-approvals.ts
• services/platform/convex/workflow/helpers/validation/steps/action.ts
• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/agent_tools/workflows/save_workflow_definition_tool.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/model/workflow_processing_records/index.ts
• services/platform/convex/agent_tools/workflows/workflow_examples_tool.ts
• services/platform/convex/agent_tools/workflows/execute_approved_workflow_creation.ts
• services/platform/convex/model/approvals/link_approvals_to_message.ts
• services/platform/convex/approvals.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx,js,jsx}: ALWAYS put imports at the top and exports at the bottom. Keep them sorted correctly
PREFER named exports. AVOID default exports (only if needed)

Files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/model/approvals/validators.ts
• services/platform/convex/agent_tools/workflows/helpers/syntax_reference.ts
• services/platform/convex/schema.ts
• services/platform/convex/workflow/helpers/validation/validate_step_config.ts
• services/platform/convex/workflow/instructions/core_instructions.ts
• services/platform/convex/workflow/helpers/validation/steps/llm.ts
• services/platform/convex/model/approvals/types.ts
• services/platform/convex/agent_tools/sub_agents/workflow_assistant_tool.ts
• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/agent_tools/workflows/create_workflow_approval.ts
• services/platform/convex/agent_tools/tool_registry.ts
• services/platform/app/(app)/dashboard/[id]/chat/components/workflow-creation-approval-card.tsx
• services/platform/convex/agent_tools/workflows/helpers/read_predefined_workflows.ts
• services/platform/convex/agent_tools/workflows/update_workflow_step_tool.ts
• services/platform/app/(app)/dashboard/[id]/chat/components/chat-interface.tsx
• services/platform/convex/lib/create_chat_agent.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/agent_tools/workflows/create_workflow_tool.ts
• services/platform/app/(app)/dashboard/[id]/chat/hooks/use-workflow-creation-approvals.ts
• services/platform/convex/workflow/helpers/validation/steps/action.ts
• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/agent_tools/workflows/save_workflow_definition_tool.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/model/workflow_processing_records/index.ts
• services/platform/convex/agent_tools/workflows/workflow_examples_tool.ts
• services/platform/convex/agent_tools/workflows/execute_approved_workflow_creation.ts
• services/platform/convex/model/approvals/link_approvals_to_message.ts
• services/platform/convex/approvals.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

**/convex/**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/convex/**/*.{ts,tsx}: CONSIDER TO use rate limiting and action caching in Convex
DO NOT use .collect(), use for await (const ... of ...) instead in Convex

Files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/model/approvals/validators.ts
• services/platform/convex/agent_tools/workflows/helpers/syntax_reference.ts
• services/platform/convex/schema.ts
• services/platform/convex/workflow/helpers/validation/validate_step_config.ts
• services/platform/convex/workflow/instructions/core_instructions.ts
• services/platform/convex/workflow/helpers/validation/steps/llm.ts
• services/platform/convex/model/approvals/types.ts
• services/platform/convex/agent_tools/sub_agents/workflow_assistant_tool.ts
• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/agent_tools/workflows/create_workflow_approval.ts
• services/platform/convex/agent_tools/tool_registry.ts
• services/platform/convex/agent_tools/workflows/helpers/read_predefined_workflows.ts
• services/platform/convex/agent_tools/workflows/update_workflow_step_tool.ts
• services/platform/convex/lib/create_chat_agent.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/agent_tools/workflows/create_workflow_tool.ts
• services/platform/convex/workflow/helpers/validation/steps/action.ts
• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/agent_tools/workflows/save_workflow_definition_tool.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/model/workflow_processing_records/index.ts
• services/platform/convex/agent_tools/workflows/workflow_examples_tool.ts
• services/platform/convex/agent_tools/workflows/execute_approved_workflow_creation.ts
• services/platform/convex/model/approvals/link_approvals_to_message.ts
• services/platform/convex/approvals.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

**/*.{tsx,jsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{tsx,jsx}: Do NOT hardcode text, use the translation hooks/functions instead for user-facing UI in React/Next.js
CONSIDER ALWAYS TO add optimistic updates with withOptimisticUpdate for useMutation. If you decide to NOT add a optimistic update you need to provide a good reason why and comment the hook
USE useMemo, useCallback and memo at the right moment in React/Next.js
DO NOT overuse useEffect in React/Next.js
USE cva if a component has multiple variants in React/Next.js
AVOID router.refresh() in Next.js
CONSIDER TO preload queries with preloadQuery and usePreloadedQuery in React with Convex

Files:

• services/platform/app/(app)/dashboard/[id]/chat/components/workflow-creation-approval-card.tsx
• services/platform/app/(app)/dashboard/[id]/chat/components/chat-interface.tsx

**/index.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (CLAUDE.md)

AVOID index barrel files (only if it makes sense to group)

Files:

• services/platform/convex/model/workflow_processing_records/index.ts

🧠 Learnings (50)

📚 Learning: 2025-10-03T11:34:20.628Z

Learnt from: CR
Repo: talecorp/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-10-03T11:34:20.628Z
Learning: Applies to convex/schema.ts : Import schema helpers (defineSchema, defineTable) from convex/server

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/model/workflow_processing_records/index.ts

📚 Learning: 2025-10-03T11:34:20.628Z

Learnt from: CR
Repo: talecorp/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-10-03T11:34:20.628Z
Learning: Applies to convex/schema.ts : Always define the database schema in convex/schema.ts

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts

📚 Learning: 2025-11-30T03:53:00.316Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-11-30T03:53:00.316Z
Learning: Applies to convex/schema.ts : Always define your schema in `convex/schema.ts` and import schema definition functions from `convex/server`

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/schema.ts

📚 Learning: 2025-07-20T08:40:41.255Z

Learnt from: CR
Repo: talecorp/poc PR: 0
File: .cursor/rules/supabase.mdc:0-0
Timestamp: 2025-07-20T08:40:41.255Z
Learning: Applies to supabase/types.ts : `types.ts` was generated by the script. Never edit it manually

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts

📚 Learning: 2024-10-07T12:01:14.503Z

Learnt from: larryro
Repo: talecorp/tale PR: 1299
File: features/platform/rest-contracts/src/contracts/platform/organization/organization-contract.ts:19-21
Timestamp: 2024-10-07T12:01:14.503Z
Learning: In TypeScript files like `organization-contract.ts`, avoid suggesting adding comments above the response schema when the code logic is very simple, as it may be unnecessary.

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts

📚 Learning: 2025-12-30T03:05:07.814Z

Learnt from: larryro
Repo: tale-project/tale PR: 36
File: services/platform/convex/agent_tools/database/helpers/schema_definitions.ts:238-242
Timestamp: 2025-12-30T03:05:07.814Z
Learning: In any file under services/platform/convex/agent_tools (e.g., database/helpers/schema_definitions.ts) prefer runtime validation of identifiers like tableName coming from LLM/user input over relying on TypeScript type restrictions alone. Implement validation at call boundaries that returns descriptive, user-friendly errors (e.g., listing available options) instead of returning null or failing at compile time. This approach supports graceful error handling and better UX for misinput.

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/agent_tools/workflows/helpers/syntax_reference.ts
• services/platform/convex/agent_tools/sub_agents/workflow_assistant_tool.ts
• services/platform/convex/agent_tools/workflows/create_workflow_approval.ts
• services/platform/convex/agent_tools/tool_registry.ts
• services/platform/convex/agent_tools/workflows/helpers/read_predefined_workflows.ts
• services/platform/convex/agent_tools/workflows/update_workflow_step_tool.ts
• services/platform/convex/agent_tools/workflows/create_workflow_tool.ts
• services/platform/convex/agent_tools/workflows/save_workflow_definition_tool.ts
• services/platform/convex/agent_tools/workflows/workflow_examples_tool.ts
• services/platform/convex/agent_tools/workflows/execute_approved_workflow_creation.ts

📚 Learning: 2025-11-30T03:53:00.316Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-11-30T03:53:00.316Z
Learning: Applies to convex/**/*.ts : Use the helper TypeScript type `Id<'tableName'>` from `./_generated/dataModel` to get the type of the id for a given table

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts

📚 Learning: 2025-08-21T15:03:10.828Z

Learnt from: CR
Repo: talecorp/lanserhof PR: 0
File: .cursor/rules/supabase.mdc:0-0
Timestamp: 2025-08-21T15:03:10.828Z
Learning: Applies to supabase/types.ts : Do not edit `types.ts`; it is generated by the script

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/schema.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts

📚 Learning: 2025-11-30T03:53:00.316Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-11-30T03:53:00.316Z
Learning: Applies to convex/schema.ts : Always include all index fields in the index name (e.g., index on ['field1', 'field2'] should be named 'by_field1_and_field2')

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-12-26T03:04:07.995Z

Learnt from: larryro
Repo: tale-project/tale PR: 35
File: services/platform/convex/approvals.ts:51-62
Timestamp: 2025-12-26T03:04:07.995Z
Learning: In Convex approvals API (services/platform/convex/approvals.ts), continue the pattern of maintaining separate internalQuery functions for internal vs public API access (e.g., getApprovalInternal vs getApprovalById) even if implementations are identical. This separation preserves the ability to diverge access control patterns in the future without breaking call sites. Apply this guideline broadly to the Convex-related API files under services/platform/convex/, using the pattern services/platform/convex/**/*.ts to cover similar modules. Ensure new or refactored internal/public wrappers follow this convention and document intent where access rules may evolve.

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/model/approvals/validators.ts
• services/platform/convex/agent_tools/workflows/helpers/syntax_reference.ts
• services/platform/convex/schema.ts
• services/platform/convex/workflow/helpers/validation/validate_step_config.ts
• services/platform/convex/workflow/instructions/core_instructions.ts
• services/platform/convex/workflow/helpers/validation/steps/llm.ts
• services/platform/convex/model/approvals/types.ts
• services/platform/convex/agent_tools/sub_agents/workflow_assistant_tool.ts
• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/agent_tools/workflows/create_workflow_approval.ts
• services/platform/convex/agent_tools/tool_registry.ts
• services/platform/convex/agent_tools/workflows/helpers/read_predefined_workflows.ts
• services/platform/convex/agent_tools/workflows/update_workflow_step_tool.ts
• services/platform/convex/lib/create_chat_agent.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/agent_tools/workflows/create_workflow_tool.ts
• services/platform/convex/workflow/helpers/validation/steps/action.ts
• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/agent_tools/workflows/save_workflow_definition_tool.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/model/workflow_processing_records/index.ts
• services/platform/convex/agent_tools/workflows/workflow_examples_tool.ts
• services/platform/convex/agent_tools/workflows/execute_approved_workflow_creation.ts
• services/platform/convex/model/approvals/link_approvals_to_message.ts
• services/platform/convex/approvals.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-12-30T03:24:33.770Z

Learnt from: larryro
Repo: tale-project/tale PR: 36
File: services/platform/convex/wf_step_defs.ts:33-39
Timestamp: 2025-12-30T03:24:33.770Z
Learning: In Convex API files under services/platform/convex (e.g., wf_step_defs.ts and peers) refrain from delegating trivial single-line database calls like ctx.db.get(id) to model helpers. Use direct calls for simple operations with no extra business logic. Reserve model helpers for complex tasks (ordering, filtering, validation, transformation). This guideline applies to all .ts files in this Convex API area.

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/model/approvals/validators.ts
• services/platform/convex/agent_tools/workflows/helpers/syntax_reference.ts
• services/platform/convex/schema.ts
• services/platform/convex/workflow/helpers/validation/validate_step_config.ts
• services/platform/convex/workflow/instructions/core_instructions.ts
• services/platform/convex/workflow/helpers/validation/steps/llm.ts
• services/platform/convex/model/approvals/types.ts
• services/platform/convex/agent_tools/sub_agents/workflow_assistant_tool.ts
• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/agent_tools/workflows/create_workflow_approval.ts
• services/platform/convex/agent_tools/tool_registry.ts
• services/platform/convex/agent_tools/workflows/helpers/read_predefined_workflows.ts
• services/platform/convex/agent_tools/workflows/update_workflow_step_tool.ts
• services/platform/convex/lib/create_chat_agent.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/agent_tools/workflows/create_workflow_tool.ts
• services/platform/convex/workflow/helpers/validation/steps/action.ts
• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/agent_tools/workflows/save_workflow_definition_tool.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/model/workflow_processing_records/index.ts
• services/platform/convex/agent_tools/workflows/workflow_examples_tool.ts
• services/platform/convex/agent_tools/workflows/execute_approved_workflow_creation.ts
• services/platform/convex/model/approvals/link_approvals_to_message.ts
• services/platform/convex/approvals.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-12-30T06:21:13.183Z

Learnt from: larryro
Repo: tale-project/tale PR: 37
File: services/platform/convex/model/documents/validators.ts:89-102
Timestamp: 2025-12-30T06:21:13.183Z
Learning: Do not flag a missing trailing newline for TypeScript files in code reviews. POSIX text files should end with a trailing newline and Prettier (or your formatter) will enforce this. Treat the trailing newline as a non-issue in reviews for all TS files.

Applied to files:

• services/platform/convex/agent_tools/database/helpers/schema_definitions.ts
• services/platform/convex/model/approvals/validators.ts
• services/platform/convex/agent_tools/workflows/helpers/syntax_reference.ts
• services/platform/convex/schema.ts
• services/platform/convex/workflow/helpers/validation/validate_step_config.ts
• services/platform/convex/workflow/instructions/core_instructions.ts
• services/platform/convex/workflow/helpers/validation/steps/llm.ts
• services/platform/convex/model/approvals/types.ts
• services/platform/convex/agent_tools/sub_agents/workflow_assistant_tool.ts
• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/agent_tools/workflows/create_workflow_approval.ts
• services/platform/convex/agent_tools/tool_registry.ts
• services/platform/convex/agent_tools/workflows/helpers/read_predefined_workflows.ts
• services/platform/convex/agent_tools/workflows/update_workflow_step_tool.ts
• services/platform/convex/lib/create_chat_agent.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/agent_tools/workflows/create_workflow_tool.ts
• services/platform/app/(app)/dashboard/[id]/chat/hooks/use-workflow-creation-approvals.ts
• services/platform/convex/workflow/helpers/validation/steps/action.ts
• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/agent_tools/workflows/save_workflow_definition_tool.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/workflow/workflow_syntax_compact.ts
• services/platform/convex/model/workflow_processing_records/index.ts
• services/platform/convex/agent_tools/workflows/workflow_examples_tool.ts
• services/platform/convex/agent_tools/workflows/execute_approved_workflow_creation.ts
• services/platform/convex/model/approvals/link_approvals_to_message.ts
• services/platform/convex/approvals.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-12-15T14:44:09.823Z

Learnt from: larryro
Repo: tale-project/tale PR: 18
File: services/platform/convex/workflow/actions/conversation/conversation_action.ts:47-98
Timestamp: 2025-12-15T14:44:09.823Z
Learning: In Convex action files (services/platform/convex/workflow/actions/**/), maintaining a separate TypeScript type alongside the parametersValidator is an acceptable pattern when documented. The TypeScript type provides IDE support and compile-time checking, while the validator provides runtime validation. This intentional separation should be documented with a comment explaining the design choice.

Applied to files:

• services/platform/convex/model/approvals/validators.ts
• services/platform/convex/schema.ts
• services/platform/convex/workflow/helpers/validation/validate_step_config.ts
• services/platform/convex/workflow/instructions/core_instructions.ts
• services/platform/convex/model/approvals/types.ts
• services/platform/convex/agent_tools/workflows/create_workflow_tool.ts
• services/platform/convex/workflow/helpers/validation/steps/action.ts
• services/platform/convex/agent_tools/workflows/save_workflow_definition_tool.ts
• services/platform/convex/agent_tools/workflows/execute_approved_workflow_creation.ts
• services/platform/convex/approvals.ts

📚 Learning: 2025-12-30T06:20:46.309Z

Learnt from: larryro
Repo: tale-project/tale PR: 37
File: services/platform/convex/model/conversations/validators.ts:106-139
Timestamp: 2025-12-30T06:20:46.309Z
Learning: In services/platform/convex/model/conversations/validators.ts, conversationItemValidator and conversationWithMessagesValidator are intentionally kept as separate validators despite having identical structures. This separation serves different semantic purposes: conversationItemValidator is for list responses while conversationWithMessagesValidator is for single conversation detail views. The duplication allows future divergence when list views might need different fields than detail views for performance or feature reasons.

Applied to files:

• services/platform/convex/model/approvals/validators.ts
• services/platform/convex/workflow/actions/conversation/conversation_action.ts

📚 Learning: 2025-12-30T13:28:34.559Z

Learnt from: larryro
Repo: tale-project/tale PR: 48
File: services/platform/convex/model/documents/validators.ts:104-107
Timestamp: 2025-12-30T13:28:34.559Z
Learning: In services/platform/convex/model/**/validators.ts, sortOrderValidator is intentionally duplicated across documents, members, vendors, and products to keep models independent. This duplication is acceptable for now; avoid consolidating into a shared validators module in future PR unless it shows clear maintenance benefits. If you centralize later, ensure API compatibility and update all references accordingly.

Applied to files:

• services/platform/convex/model/approvals/validators.ts

📚 Learning: 2025-12-15T14:01:55.275Z

Learnt from: larryro
Repo: tale-project/tale PR: 18
File: services/platform/convex/workflow/actions/conversation/helpers/update_conversations.ts:7-10
Timestamp: 2025-12-15T14:01:55.275Z
Learning: In Convex action helpers (services/platform/convex/workflow/actions/**/helpers/*.ts), using Record<string, unknown> for update parameters is acceptable when field validation is handled at the mutation level in Convex. This provides flexibility for dynamic field updates while keeping validation centralized at the mutation layer.

Applied to files:

• services/platform/convex/model/approvals/validators.ts
• services/platform/convex/schema.ts
• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/agent_tools/workflows/create_workflow_approval.ts
• services/platform/convex/workflow/helpers/validation/steps/action.ts
• services/platform/convex/approvals.ts

📚 Learning: 2025-10-03T11:34:20.628Z

Learnt from: CR
Repo: talecorp/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-10-03T11:34:20.628Z
Learning: Applies to convex/**/*.{ts,js} : Use the documented Convex validators for all supported types (e.g., v.id, v.int64, v.number, v.boolean, v.string, v.bytes, v.array, v.object, v.record)

Applied to files:

• services/platform/convex/model/approvals/validators.ts

📚 Learning: 2025-12-30T06:20:18.848Z

Learnt from: larryro
Repo: tale-project/tale PR: 37
File: services/platform/convex/model/conversations/validators.ts:31-39
Timestamp: 2025-12-30T06:20:18.848Z
Learning: In services/platform/convex/model/conversations/validators.ts, the messageValidator intentionally uses v.string() for the status field because message statuses are dynamic and come from different sources (email providers, internal state, etc.) and are not yet constrained to a fixed set of values.

Applied to files:

• services/platform/convex/model/approvals/validators.ts

📚 Learning: 2025-11-30T03:53:00.316Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-11-30T03:53:00.316Z
Learning: Applies to convex/**/*.ts : Always include argument and return validators for all Convex functions (query, internalQuery, mutation, internalMutation, action, internalAction)

Applied to files:

• services/platform/convex/model/approvals/validators.ts

📚 Learning: 2025-10-03T11:34:20.628Z

Learnt from: CR
Repo: talecorp/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-10-03T11:34:20.628Z
Learning: Applies to convex/**/*.ts : Ensure TypeScript Record key/value types match validators (e.g., Record<Id<'users'>, string>)

Applied to files:

• services/platform/convex/model/approvals/validators.ts

📚 Learning: 2025-11-30T03:53:00.316Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-11-30T03:53:00.316Z
Learning: Applies to convex/**/*.ts : Use `v.id(tableName)` validator for document IDs, and use strict TypeScript types with `Id<'tableName'>` instead of generic string types for function arguments and returns

Applied to files:

• services/platform/convex/model/approvals/validators.ts

📚 Learning: 2026-01-01T09:48:06.791Z

Learnt from: larryro
Repo: tale-project/tale PR: 58
File: services/platform/convex/model/vendors/validators.ts:41-41
Timestamp: 2026-01-01T09:48:06.791Z
Learning: Use v.string() for organizationId fields in Convex schemas instead of v.id('organizations'), since organization identifiers come from the external Better Auth system and are external IDs, not Convex document IDs. This pattern should be applied consistently across all validators (documents, products, customers, vendors, integrations, etc.) and across all files with validators, not just this one.

Applied to files:

• services/platform/convex/model/approvals/validators.ts

📚 Learning: 2025-12-30T03:53:06.120Z

Learnt from: larryro
Repo: tale-project/tale PR: 36
File: services/platform/convex/workflow_assistant_agent.ts:94-107
Timestamp: 2025-12-30T03:53:06.120Z
Learning: In services/platform/convex/workflow_assistant_agent.ts, using `any` type for step parameters during toonification (compact representation) is acceptable when step structures vary significantly by stepType (llm, condition, action, loop). The sanitization approach extracts only needed fields for context, and strict typing with complex discriminated unions would add maintenance burden without practical benefit since the data is only used for compact representation, not type-specific processing.

Applied to files:

• services/platform/convex/schema.ts
• services/platform/convex/workflow/helpers/validation/validate_step_config.ts
• services/platform/convex/workflow/instructions/core_instructions.ts
• services/platform/convex/model/approvals/types.ts
• services/platform/convex/agent_tools/workflows/update_workflow_step_tool.ts
• services/platform/convex/lib/create_chat_agent.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/workflow/helpers/validation/steps/action.ts
• services/platform/convex/agent_tools/workflows/save_workflow_definition_tool.ts

📚 Learning: 2025-12-30T03:14:15.467Z

Learnt from: larryro
Repo: tale-project/tale PR: 36
File: services/platform/convex/predefined_workflows/product_relationship_analysis.ts:332-367
Timestamp: 2025-12-30T03:14:15.467Z
Learning: In product_relationship_analysis.ts and similar predefined workflows with outputSchema: the design intentionally uses `additionalProperties: false` only at the root level of JSON schemas for LLM outputs, not at nested item levels. This allows LLMs to include extra context fields in individual items while ensuring the overall structure is valid. This is a deliberate architectural choice to balance strict validation with LLM flexibility.

Applied to files:

• services/platform/convex/schema.ts
• services/platform/convex/workflow/helpers/validation/steps/llm.ts

📚 Learning: 2025-12-15T14:43:53.478Z

Learnt from: larryro
Repo: tale-project/tale PR: 18
File: services/platform/convex/agent_tools/convex_tools/workflows/update_workflow_step_tool.ts:20-21
Timestamp: 2025-12-15T14:43:53.478Z
Learning: In the tale-project/tale repository, when constants are duplicated between files (e.g., validStepTypes in update_workflow_step_tool.ts and validate_step_config.ts), the preference is to maintain self-contained file structure with sync comments documenting the relationship, rather than importing shared constants. This approach prioritizes clear, self-contained structure over strict DRY principles.

Applied to files:

• services/platform/convex/workflow/helpers/validation/validate_step_config.ts
• services/platform/convex/workflow/instructions/core_instructions.ts
• services/platform/convex/agent_tools/workflows/update_workflow_step_tool.ts
• services/platform/convex/agent_tools/workflows/save_workflow_definition_tool.ts

📚 Learning: 2025-12-30T03:05:13.035Z

Learnt from: larryro
Repo: tale-project/tale PR: 36
File: services/platform/convex/agent_tools/database/helpers/schema_definitions.ts:238-242
Timestamp: 2025-12-30T03:05:13.035Z
Learning: For AI agent tool APIs in services/platform/convex/agent_tools that receive tableName or similar identifiers from runtime LLM/user input, prefer runtime validation with descriptive error messages over compile-time TypeScript type restrictions. The pattern of returning null and handling validation at the caller level with helpful error messages (listing available options) is the preferred approach for graceful error handling.

Applied to files:

• services/platform/convex/workflow/helpers/validation/steps/llm.ts
• services/platform/convex/lib/create_chat_agent.ts

📚 Learning: 2025-12-30T03:47:44.914Z

Learnt from: larryro
Repo: tale-project/tale PR: 36
File: services/platform/convex/agent_tools/workflows/workflow_read_tool.ts:127-144
Timestamp: 2025-12-30T03:47:44.914Z
Learning: In AI agent tool APIs in services/platform/convex/agent_tools/workflows, using `any` type for return data that varies significantly based on runtime conditions (e.g., step structures in workflow_read_tool.ts that differ by stepType: LLM, code, condition, etc.) is acceptable when the caller (AI agent) treats the data as opaque for inspection. Strict typing with complex union types provides limited practical benefit in these cases.

Applied to files:

• services/platform/convex/agent_tools/sub_agents/workflow_assistant_tool.ts
• services/platform/convex/agent_tools/workflows/update_workflow_step_tool.ts
• services/platform/convex/lib/create_chat_agent.ts
• services/platform/convex/lib/create_workflow_agent.ts
• services/platform/convex/agent_tools/workflows/create_workflow_tool.ts

📚 Learning: 2025-12-15T14:44:04.593Z

Learnt from: larryro
Repo: tale-project/tale PR: 18
File: services/platform/convex/workflow/actions/conversation/conversation_action.ts:47-98
Timestamp: 2025-12-15T14:44:04.593Z
Learning: In Convex action files under services/platform/convex/workflow/actions/**, prefer maintaining a separate TypeScript type for the action parameters alongside the runtime validators (parametersValidator). The TypeScript type provides IDE support and compile-time checking, while the validator handles runtime validation. Document this design with a clear comment next to the type/validator pair explaining the rationale (e.g., separate types for static typing vs runtime checks, and how they relate). This pattern applies across all actions in this directory, not just a single file.

Applied to files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts

📚 Learning: 2025-07-20T08:40:24.693Z

Learnt from: CR
Repo: talecorp/poc PR: 0
File: .cursor/rules/ai.mdc:0-0
Timestamp: 2025-07-20T08:40:24.693Z
Learning: Applies to **/actions/*.ts : For text generation, use the `generateObject` or similar functions from the AI SDK

Applied to files:

• services/platform/convex/workflow/actions/conversation/conversation_action.ts
• services/platform/convex/workflow/helpers/validation/steps/action.ts

📚 Learning: 2025-11-30T12:29:39.745Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/workspace_rules.mdc:0-0
Timestamp: 2025-11-30T12:29:39.745Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Use Vercel AI SDK with OpenAI (import from 'ai' and 'ai-sdk/openai') - never use raw OpenAI SDK or other AI providers like OpenRouter

Applied to files:

• .env.example

📚 Learning: 2025-12-19T04:29:09.246Z

Learnt from: larryro
Repo: tale-project/tale PR: 26
File: services/platform/app/(app)/dashboard/[id]/(knowledge)/documents/components/rag-status-badge.tsx:82-92
Timestamp: 2025-12-19T04:29:09.246Z
Learning: In services/platform/app/(app)/dashboard/[id]/(knowledge)/documents/components/rag-status-badge.tsx, the team prefers using router.refresh() for polling in-progress RAG statuses over targeted status fetching, prioritizing simplicity and state consistency given the expected low number of concurrent indexing jobs (1-3 documents).

Applied to files:

• services/platform/app/(app)/dashboard/[id]/chat/components/workflow-creation-approval-card.tsx

📚 Learning: 2025-12-26T02:23:20.245Z

Learnt from: larryro
Repo: tale-project/tale PR: 35
File: services/platform/app/(app)/dashboard/[id]/chat/components/integration-approval-card.tsx:58-90
Timestamp: 2025-12-26T02:23:20.245Z
Learning: In services/platform/app/(app)/dashboard/[id]/chat/components/integration-approval-card.tsx, prefer reading the approving user from the authenticated session context rather than passing a userId from the frontend. The hardcoded 'user' string can be acceptable only as a temporary placeholder during the initial implementation until a user profile feature is added; plan to replace with proper user identity via session context or user service once backend supports it.

Applied to files:

• services/platform/app/(app)/dashboard/[id]/chat/components/workflow-creation-approval-card.tsx
• services/platform/app/(app)/dashboard/[id]/chat/components/chat-interface.tsx

📚 Learning: 2025-12-26T03:04:19.196Z

Learnt from: larryro
Repo: tale-project/tale PR: 35
File: services/platform/convex/approvals.ts:51-62
Timestamp: 2025-12-26T03:04:19.196Z
Learning: In Convex approvals API (services/platform/convex/approvals.ts), the codebase intentionally maintains separate internalQuery functions for internal vs public API access (e.g., getApprovalInternal vs getApprovalById) even when implementations are identical. This separation allows for future access control pattern divergence without breaking call sites.

Applied to files:

• services/platform/app/(app)/dashboard/[id]/chat/components/chat-interface.tsx
• services/platform/app/(app)/dashboard/[id]/chat/hooks/use-workflow-creation-approvals.ts

📚 Learning: 2025-12-20T13:38:13.773Z

Learnt from: larryro
Repo: tale-project/tale PR: 30
File: services/platform/convex/model/chat_agent/chat_with_agent.ts:130-144
Timestamp: 2025-12-20T13:38:13.773Z
Learning: In services/platform/convex/model/chat_agent/chat_with_agent.ts, image fileIds are intentionally displayed as `*(fileId: ${attachment.fileId})*` in the markdown because the AI needs to reference them from thread history for re-analysis using the image tool. This is a business/developer tool, not consumer-facing, so technical metadata visibility is acceptable.

Applied to files:

• services/platform/convex/lib/create_chat_agent.ts

📚 Learning: 2025-08-21T14:59:36.874Z

Learnt from: CR
Repo: talecorp/lanserhof PR: 0
File: .cursorrules:0-0
Timestamp: 2025-08-21T14:59:36.874Z
Learning: Agents must start by checking language requirements, stop if non-English text appears, verify AI SDK usage, and follow existing patterns

Applied to files:

• services/platform/convex/lib/create_workflow_agent.ts

📚 Learning: 2025-12-26T02:23:30.037Z

Learnt from: larryro
Repo: tale-project/tale PR: 35
File: services/platform/app/(app)/dashboard/[id]/chat/components/integration-approval-card.tsx:58-90
Timestamp: 2025-12-26T02:23:30.037Z
Learning: In the Tale platform approval workflow (services/platform), the backend tracks which user performed approval actions via the authenticated session context rather than requiring explicit user ID passing from the frontend. The hardcoded 'user' string in approval operations is acceptable for initial implementation until the user profile feature is added.

Applied to files:

• services/platform/app/(app)/dashboard/[id]/chat/hooks/use-workflow-creation-approvals.ts
• services/platform/convex/approvals.ts

📚 Learning: 2025-10-03T11:34:20.628Z

Learnt from: CR
Repo: talecorp/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-10-03T11:34:20.628Z
Learning: Applies to convex/**/*.{ts,js} : Query indexed fields in the same order as the index definition; create separate indexes for alternate orders

Applied to files:

• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/model/workflow_processing_records/index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-11-30T03:53:00.316Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-11-30T03:53:00.316Z
Learning: Applies to convex/**/*.ts : Index fields must be queried in the same order they are defined; create separate indexes if you need to query by different field orderings

Applied to files:

• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/model/workflow_processing_records/index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-10-03T11:34:20.628Z

Learnt from: CR
Repo: talecorp/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-10-03T11:34:20.628Z
Learning: Applies to convex/schema.ts : Include all indexed fields in the index name (e.g., by_field1_and_field2)

Applied to files:

• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-10-03T11:34:20.628Z

Learnt from: CR
Repo: talecorp/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-10-03T11:34:20.628Z
Learning: Applies to convex/**/*.{ts,js} : Do not use .filter() in queries; define an index and use withIndex instead

Applied to files:

• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-12-30T03:12:20.441Z

Learnt from: larryro
Repo: tale-project/tale PR: 36
File: services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts:34-36
Timestamp: 2025-12-30T03:12:20.441Z
Learning: In Convex workflow processing index selection (services/platform/convex/model/workflow_processing_records/index_selection/), the ScoringResult interface returns both `values` and `indexableConditions` with distinct purposes: `values` contains field-value pairs for equality conditions used directly in .withIndex() calls for index query construction, while `indexableConditions` contains all conditions (including comparisons) that participate in index selection scoring and may require additional handling (e.g., .gt(), .lt() filters).
<!-- [add_learning]
In services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts and related query building code, equality conditions populate both the `values` map (for .eq() queries) and the `indexableConditions` array, while comparison conditions (>, <, >=, <=) only populate `indexableConditions` for subsequent range query application.

Applied to files:

• services/platform/convex/model/workflow_processing_records/get_table_indexes.ts
• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-11-30T03:53:00.316Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-11-30T03:53:00.316Z
Learning: Applies to convex/**/*.ts : Do NOT use `filter` in queries; instead, define an index in the schema and use `withIndex` with proper field matching

Applied to files:

• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts
• services/platform/convex/model/workflow_processing_records/index_selection/types.ts
• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-07-19T15:30:00.886Z

Learnt from: CR
Repo: talecorp/poc PR: 0
File: .cursor/rules/core-rules.mdc:0-0
Timestamp: 2025-07-19T15:30:00.886Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Extract reusable functions, add comprehensive error handling, improve naming and documentation, and remove temporary debug code during optimization

Applied to files:

• services/platform/convex/model/workflow_processing_records/index_selection/select_optimal_index.ts

📚 Learning: 2025-11-30T12:29:39.745Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/workspace_rules.mdc:0-0
Timestamp: 2025-11-30T12:29:39.745Z
Learning: Applies to convex/*.ts : Split existing Convex modules that export multiple functions into separate files with one function per file, except for explicitly designated thin wrapper modules

Applied to files:

• services/platform/convex/model/workflow_processing_records/index.ts

📚 Learning: 2025-11-30T12:29:39.745Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/workspace_rules.mdc:0-0
Timestamp: 2025-11-30T12:29:39.745Z
Learning: Applies to services/**/convex/*.ts : Thin wrapper API modules in services may export multiple Convex functions as thin wrappers that delegate to model helpers, must use snake_case file names and camelCase export names, and must not contain business logic

Applied to files:

• services/platform/convex/model/workflow_processing_records/index.ts

📚 Learning: 2025-11-30T03:53:00.316Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-11-30T03:53:00.316Z
Learning: Applies to convex/**/*.ts : Always use the new Convex function syntax with `query`, `mutation`, `internalQuery`, `internalMutation`, `action`, or `internalAction` with explicit `args`, `returns`, and `handler` properties

Applied to files:

• services/platform/convex/model/approvals/link_approvals_to_message.ts
• services/platform/convex/approvals.ts

📚 Learning: 2025-11-30T03:53:00.316Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-11-30T03:53:00.316Z
Learning: Applies to convex/**/*.ts : Try to use as few calls from actions to queries and mutations as possible to avoid race conditions, since queries and mutations are transactions

Applied to files:

• services/platform/convex/model/approvals/link_approvals_to_message.ts
• services/platform/convex/approvals.ts

📚 Learning: 2025-10-03T11:34:20.628Z

Learnt from: CR
Repo: talecorp/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-10-03T11:34:20.628Z
Learning: Applies to convex/**/*.{ts,js} : Use withSearchIndex and q.search for full-text search queries

Applied to files:

• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-10-03T11:34:20.628Z

Learnt from: CR
Repo: talecorp/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-10-03T11:34:20.628Z
Learning: Applies to convex/**/*.{ts,js} : Explicitly set query order via .order('asc'|'desc'); default is ascending _creationTime

Applied to files:

• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

📚 Learning: 2025-11-30T03:53:00.316Z

Learnt from: CR
Repo: tale-project/poc2 PR: 0
File: .cursor/rules/convex_rules.mdc:0-0
Timestamp: 2025-11-30T03:53:00.316Z
Learning: Applies to convex/**/*.ts : Be strict with types, particularly around IDs of documents; use `Id<'tableName'>` rather than `string` for function arguments and returns

Applied to files:

• services/platform/convex/model/workflow_processing_records/index_selection/score_index.ts

🧬 Code graph analysis (8)

services/platform/convex/agent_tools/sub_agents/workflow_assistant_tool.ts (2)

services/platform/convex/lib/create_workflow_agent.ts (1)

• createWorkflowAgent (21-86)

services/platform/convex/agent_tools/types.ts (1)

• ToolDefinition (19-22)

services/platform/convex/agent_tools/workflows/create_workflow_approval.ts (2)

services/platform/convex/model/approvals/types.ts (1)

• WorkflowCreationMetadata (49-71)

services/platform/convex/approvals.ts (1)

• createApproval (19-36)

services/platform/convex/lib/create_workflow_agent.ts (2)

services/platform/convex/workflow/instructions/core_instructions.ts (2)

• WORKFLOW_AGENT_CORE_INSTRUCTIONS (8-57)
• WORKFLOW_AGENT_DELEGATION_INSTRUCTIONS (62-86)

services/platform/convex/lib/create_agent_config.ts (1)

• createAgentConfig (15-105)

services/platform/convex/agent_tools/workflows/create_workflow_tool.ts (1)

services/platform/convex/agent_tools/types.ts (1)

• ToolDefinition (19-22)

services/platform/app/(app)/dashboard/[id]/chat/hooks/use-workflow-creation-approvals.ts (1)

services/platform/convex/model/approvals/types.ts (1)

• WorkflowCreationMetadata (49-71)

services/platform/convex/agent_tools/workflows/workflow_examples_tool.ts (3)

services/platform/convex/agent_tools/types.ts (1)

• ToolDefinition (19-22)

services/platform/convex/agent_tools/workflows/helpers/read_predefined_workflows.ts (1)

• listPredefinedWorkflows (114-147)

services/platform/convex/agent_tools/workflows/helpers/syntax_reference.ts (1)

• getSyntaxReference (453-477)

services/platform/convex/agent_tools/workflows/execute_approved_workflow_creation.ts (3)

services/platform/convex/approvals.ts (1)

• executeApprovedWorkflowCreation (375-424)

services/platform/convex/model/approvals/types.ts (1)

• WorkflowCreationMetadata (49-71)

services/platform/scripts/dev.mjs (1)

• siteUrl (285-285)

services/platform/convex/approvals.ts (1)

services/platform/convex/agent_tools/workflows/execute_approved_workflow_creation.ts (1)

• executeApprovedWorkflowCreation (17-136)

🪛 dotenv-linter (4.0.0)

.env.example

[warning] 61-61: [UnorderedKey] The OPENAI_CODING_MODEL key should go before the OPENAI_MODEL key

(UnorderedKey)