new proposals

Author: djanogly

openspec/changes/add-help-center-links-in-ai-responses/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-03

openspec/changes/add-help-center-links-in-ai-responses/design.md

@@ -0,0 +1,68 @@
+## Context
+
+AI source attribution exists, but actionable source navigation is missing in key UX paths. Visitors see source titles but cannot click through to relevant articles directly from AI responses.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Provide clickable source links for article-backed AI responses.
+- Keep source attribution structured and consistent across widget and AI review surfaces.
+- Handle mixed source types gracefully.
+
+**Non-Goals:**
+- Redesigning full help center UI navigation.
+- Changing AI retrieval/ranking logic in this change.
+
+## Decisions
+
+### 1) Enrich source metadata with linkable article identity
+
+Decision:
+- Include link-ready metadata for article sources (for example article ID and navigable target) in stored AI response payloads.
+
+Rationale:
+- Rendering layers need explicit data to build reliable links.
+
+Alternatives considered:
+- Infer links from title text in UI. Rejected due to ambiguity and fragility.
+
+### 2) Render source chips/links in widget message context
+
+Decision:
+- Widget AI message component renders source links as clickable UI elements that route to article detail.
+
+Rationale:
+- Improves self-service resolution directly inside conversation flow.
+
+Alternatives considered:
+- Keep plain text only. Rejected due to poor UX and traceability.
+
+### 3) Keep fallback handling for non-article sources
+
+Decision:
+- Non-linkable sources remain labeled attribution entries without broken link affordances.
+
+Rationale:
+- Maintains source transparency without invalid navigation.
+
+## Risks / Trade-offs
+
+- [Risk] Link targets could become stale if article records are removed.
+  - Mitigation: resolve targets at render time and fallback to title-only entry when unavailable.
+- [Risk] Extra metadata may increase payload size.
+  - Mitigation: keep source payload minimal and structured.
+
+## Migration Plan
+
+1. Extend source metadata schema and response serialization for linkable article fields.
+2. Update widget AI source rendering to show clickable article entries.
+3. Update AI review/chat source renderers to use linkable metadata.
+4. Add tests for link rendering and non-article fallback behavior.
+
+Rollback:
+- Revert UI link rendering while preserving source metadata extension for future use.
+
+## Open Questions
+
+- Should source links include deep links for web inbox contexts in this same change?
+- Do we show per-source confidence/rank in UI now or later?

openspec/changes/add-help-center-links-in-ai-responses/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+AI responses currently store source metadata as type/id/title, but widget chat only renders source titles as plain text and does not provide direct article navigation. This weakens answer traceability and makes self-serve follow-up harder for visitors.
+
+## What Changes
+
+- Extend AI response source metadata to include linkable Help Center reference data for article sources.
+- Render AI source references in widget chat as clickable article links that open corresponding articles.
+- Surface the same linkable source references in AI review/chat contexts where appropriate.
+- Preserve non-article source handling without broken links.
+
+## Capabilities
+
+### New Capabilities
+
+- `ai-help-center-linked-sources`: AI responses expose linkable Help Center article sources in chat/review surfaces.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- Convex AI response storage and query payload shape for sources.
+- Widget chat rendering of AI source references.
+- Inbox AI review/source presentation logic.

openspec/changes/add-help-center-links-in-ai-responses/specs/ai-help-center-linked-sources/spec.md

@@ -0,0 +1,28 @@
+## ADDED Requirements
+
+### Requirement: AI response source records MUST include linkable metadata for article sources
+
+AI response source entries associated with Help Center articles SHALL include metadata required for reliable article navigation.
+
+#### Scenario: AI response references published article
+
+- **WHEN** AI response includes a Help Center article source
+- **THEN** source metadata SHALL include linkable article identity fields for UI navigation
+
+### Requirement: Widget AI messages MUST render article sources as clickable links
+
+Widget conversation UI SHALL render article-backed AI sources as clickable elements that open the corresponding article context.
+
+#### Scenario: Visitor taps article source in AI message
+
+- **WHEN** widget displays an AI message with article sources
+- **THEN** selecting a source SHALL open the referenced article view
+
+### Requirement: Non-article sources MUST degrade gracefully
+
+Sources without linkable article targets SHALL remain visible as attribution text and MUST NOT render broken links.
+
+#### Scenario: AI response includes snippet source
+
+- **WHEN** AI response includes a non-article source
+- **THEN** UI SHALL display source attribution without invalid navigation affordances

openspec/changes/add-help-center-links-in-ai-responses/tasks.md

@@ -0,0 +1,19 @@
+## 1. Source Metadata Extension
+
+- [ ] 1.1 Extend AI response source payload shape with linkable article metadata fields.
+- [ ] 1.2 Update source serialization/query code to return enriched metadata.
+
+## 2. UI Integration
+
+- [ ] 2.1 Render clickable article source links in widget AI message UI.
+- [ ] 2.2 Update AI review/chat source rendering to use linkable metadata where available.
+
+## 3. Verification
+
+- [ ] 3.1 Add tests for article link rendering and navigation behavior.
+- [ ] 3.2 Add tests for non-article source fallback handling.
+
+## 4. Cleanup
+
+- [ ] 4.1 Remove ad-hoc source-title-only rendering paths where replaced.
+- [ ] 4.2 Document source metadata contract for AI and UI contributors.

openspec/changes/ai-autotranslate-conversation-language-support/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-03

openspec/changes/ai-autotranslate-conversation-language-support/design.md

@@ -0,0 +1,72 @@
+## Context
+
+Support teams and visitors can communicate in different languages, but current AI and inbox flows do not provide translation mediation. A robust implementation needs translation transparency, language preference memory, and safe fallbacks when translation fails.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Detect/store conversation language context.
+- Provide automatic translation for AI replies and optional agent-assisted replies.
+- Preserve original text for audit/review and quality checks.
+- Expose translation status in chat/review UI.
+
+**Non-Goals:**
+- Building a standalone human translator management system.
+- Guaranteeing perfect translation quality for all languages.
+
+## Decisions
+
+### 1) Persist language metadata and dual-text payloads
+
+Decision:
+- Store detected/source language plus translated output while retaining original message text.
+
+Rationale:
+- Maintains transparency and enables quality review.
+
+Alternatives considered:
+- Replace original message with translated-only text. Rejected due to audit and trust concerns.
+
+### 2) Translation pipeline integrated at AI and agent reply boundaries
+
+Decision:
+- Integrate translation in AI generation and agent send paths so visitors receive messages in conversation-preferred language.
+
+Rationale:
+- Centralized translation boundary keeps UI clients simpler and consistent.
+
+Alternatives considered:
+- Client-only translation. Rejected due to fragmentation and policy drift.
+
+### 3) Safe fallbacks with explicit status
+
+Decision:
+- If translation fails, preserve original delivery and mark translation status for review.
+
+Rationale:
+- Avoids message loss and provides operational visibility.
+
+## Risks / Trade-offs
+
+- [Risk] Added latency from translation step.
+  - Mitigation: async optimization and short-response caching where safe.
+- [Risk] Translation errors could misrepresent intent.
+  - Mitigation: preserve original text and expose "view original" controls.
+- [Risk] Higher model/provider cost.
+  - Mitigation: configurable language scope and threshold-based translation triggers.
+
+## Migration Plan
+
+1. Add schema fields for language metadata and translated/original content traces.
+2. Implement translation service integration for AI and agent reply flows.
+3. Add UI indicators/toggles for translation visibility.
+4. Add tests for language detection, translation success/fallback, and review visibility.
+5. Roll out behind workspace-level feature flag.
+
+Rollback:
+- Disable feature flag and bypass translation step while retaining schema backward compatibility.
+
+## Open Questions
+
+- Which translation provider(s) are acceptable for initial rollout?
+- Should workspaces configure source/target language policy or rely on automatic detection only?

openspec/changes/ai-autotranslate-conversation-language-support/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+Current messaging and AI flows assume shared language context and do not provide automatic translation between visitors and support teams. This creates friction for multilingual conversations and limits self-serve AI usefulness across languages.
+
+## What Changes
+
+- Add conversation-level language detection and preference tracking for visitor interactions.
+- Introduce automatic translation support for AI responses and optional agent reply translation workflows.
+- Persist original and translated message forms so teams can review exact source text.
+- Add UI affordances to display translation status and allow viewing original content.
+
+## Capabilities
+
+### New Capabilities
+
+- `ai-conversation-autotranslate`: Conversations can automatically translate between visitor language and support/AI language with traceable original text.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- Convex messaging/AI pipelines and schema for language metadata and translation payloads.
+- Web inbox and widget/mobile messaging UI for translation display controls.
+- AI response generation flow and related analytics/review behavior.

openspec/changes/ai-autotranslate-conversation-language-support/specs/ai-conversation-autotranslate/spec.md

@@ -0,0 +1,36 @@
+## ADDED Requirements
+
+### Requirement: Conversation flows MUST track language context for translation
+
+Conversation messaging and AI workflows SHALL track detected/source language and preferred output language context.
+
+#### Scenario: Visitor sends message in non-default language
+
+- **WHEN** a visitor message is detected in a language different from workspace default
+- **THEN** conversation language context SHALL be updated with detected/source language metadata
+
+### Requirement: AI and agent replies MUST support automatic delivery translation
+
+AI responses and opted-in agent replies SHALL be translated to conversation-preferred visitor language while preserving original source text.
+
+#### Scenario: AI responds in visitor-preferred language
+
+- **WHEN** AI generates a response for a conversation with preferred language set
+- **THEN** delivered content SHALL be translated to the preferred language
+- **AND** original generated text SHALL remain available for review
+
+#### Scenario: Agent sends translated reply
+
+- **WHEN** an agent sends a reply with auto-translate enabled
+- **THEN** visitor-visible message SHALL be translated to the target language
+- **AND** original agent text SHALL be retained for audit/review
+
+### Requirement: Translation failures MUST degrade safely with explicit status
+
+If translation cannot be completed, message delivery SHALL continue with original text and explicit translation status metadata.
+
+#### Scenario: Translation service fails
+
+- **WHEN** translation provider returns an error or timeout
+- **THEN** original message text SHALL still be delivered
+- **AND** translation status SHALL indicate failure for operational review

openspec/changes/ai-autotranslate-conversation-language-support/tasks.md

@@ -0,0 +1,20 @@
+## 1. Language Metadata Foundation
+
+- [ ] 1.1 Define schema fields for conversation/message language metadata and original/translated text traces.
+- [ ] 1.2 Implement language detection and preferred-language persistence in conversation flows.
+
+## 2. Translation Pipeline Integration
+
+- [ ] 2.1 Integrate translation into AI response generation flow.
+- [ ] 2.2 Integrate optional translation into agent reply send path.
+- [ ] 2.3 Implement safe fallback behavior and status metadata on translation failure.
+
+## 3. UI And Review Surfaces
+
+- [ ] 3.1 Add translation status and original-text visibility controls in relevant chat/review surfaces.
+- [ ] 3.2 Add workspace-level feature flag/configuration controls for rollout.
+
+## 4. Verification
+
+- [ ] 4.1 Add tests for detection, translation success, and failure fallback flows.
+- [ ] 4.2 Run targeted web/widget/mobile/convex checks for touched translation paths.