diff --git a/apps/landing/src/app/docs/page.tsx b/apps/landing/src/app/docs/page.tsx index f0d31c3..f29812a 100644 --- a/apps/landing/src/app/docs/page.tsx +++ b/apps/landing/src/app/docs/page.tsx @@ -1,24 +1,27 @@ -import type { Metadata } from "next"; +import { Metadata } from "next"; import Link from "next/link"; import { - Terminal, - Server, BookOpen, Code2, - ExternalLink, + Server, Smartphone, - Bot, + Terminal, Layout, Blocks, Sparkles, + ExternalLink, + Bot, } from "lucide-react"; import { buttonVariants, cn } from "@opencom/ui"; -import { Section, SectionHeader, FeatureCard, Screenshot } from "@/components/sections"; +import { Section, SectionHeader, FeatureCard } from "@/components/sections"; import { OPENCOM_GITHUB_DOCS_URL, OPENCOM_GITHUB_REPO_URL, OPENCOM_HOSTED_ONBOARDING_URL, } from "@/lib/links"; + +import { WidgetHomeGraphic } from "@/components/landing/graphics/widget-home-graphic"; +import { ToursGraphic } from "@/components/landing/graphics/tours-graphic"; import { createLandingPageMetadata } from "@/lib/metadata"; export const metadata: Metadata = createLandingPageMetadata({ @@ -221,8 +224,18 @@ export default function DocsPage() {
- - +
+
+
+ +
+
+
+
+
+ +
+
diff --git a/apps/landing/src/app/features/page.tsx b/apps/landing/src/app/features/page.tsx index 6a3fe0c..ff106d7 100644 --- a/apps/landing/src/app/features/page.tsx +++ b/apps/landing/src/app/features/page.tsx @@ -17,7 +17,7 @@ import { Check, Sparkles, } from "lucide-react"; -import { Section, SectionHeader, FeatureCard, Screenshot, CTA } from "@/components/sections"; +import { Section, SectionHeader, FeatureCard, CTA } from "@/components/sections"; import { OPENCOM_GITHUB_DOCS_URL, OPENCOM_HOSTED_ONBOARDING_URL } from "@/lib/links"; import { InboxGraphic } from "@/components/landing/graphics/inbox-graphic"; @@ -27,6 +27,9 @@ import { TicketsGraphic } from "@/components/landing/graphics/tickets-graphic"; import { SurveysGraphic } from "@/components/landing/graphics/surveys-graphic"; import { CampaignsGraphic } from "@/components/landing/graphics/campaigns-graphic"; import { ReportsGraphic } from "@/components/landing/graphics/reports-graphic"; +import { KnowledgeBaseGraphic } from "@/components/landing/graphics/knowledge-graphic"; +import { ChecklistsGraphic } from "@/components/landing/graphics/checklists-graphic"; +import { TooltipsGraphic } from "@/components/landing/graphics/tooltips-graphic"; export const metadata: Metadata = { title: "Features | Opencom", @@ -71,7 +74,7 @@ const featureCategories = [ title: "Knowledge Hub", description: "Self-service help center with searchable articles, snippets, and folders.", icon: BookOpen, - screenshot: "/screenshots/web-knowledge.png", + Graphic: KnowledgeBaseGraphic, features: [ "Article management with folders", "Saved reply snippets", @@ -146,7 +149,7 @@ const featureCategories = [ title: "Checklists", description: "Guide users through onboarding with task lists.", icon: ListChecks, - screenshot: "/screenshots/web-checklists.png", + Graphic: ChecklistsGraphic, features: [ "Multi-step onboarding checklists", "Task completion tracking", @@ -161,7 +164,7 @@ const featureCategories = [ title: "Tooltips", description: "Contextual hints attached to page elements.", icon: MousePointerClick, - screenshot: "/screenshots/web-tooltips.png", + Graphic: TooltipsGraphic, features: [ "On-hover tooltips", "Click-triggered beacons", @@ -263,18 +266,14 @@ export default function FeaturesPage() {
- {category.Graphic ? ( -
- {/* Subtle inner glow */} -
- -
- -
+
+ {/* Subtle inner glow */} +
+ +
+
- ) : ( - - )} +
diff --git a/apps/landing/src/app/support/page.tsx b/apps/landing/src/app/support/page.tsx index 8f1cbd2..dff4763 100644 --- a/apps/landing/src/app/support/page.tsx +++ b/apps/landing/src/app/support/page.tsx @@ -1,9 +1,12 @@ import type { Metadata } from "next"; import { Clock3, LifeBuoy, MessageCircle, MousePointerClick } from "lucide-react"; -import { Screenshot, Section, SectionHeader } from "@/components/sections"; +import { Section, SectionHeader } from "@/components/sections"; import { WidgetCtaPanel } from "@/components/support/widget-cta-panel"; import { createLandingPageMetadata } from "@/lib/metadata"; +import { WidgetHomeGraphic } from "@/components/landing/graphics/widget-home-graphic"; +import { WidgetChatGraphic } from "@/components/landing/graphics/widget-chat-graphic"; + export const metadata: Metadata = createLandingPageMetadata({ title: "Support | Opencom", description: @@ -64,8 +67,18 @@ export default function SupportPage() {
- - +
+
+
+ +
+
+
+
+
+ +
+
diff --git a/apps/landing/src/components/landing/graphics/checklists-graphic.tsx b/apps/landing/src/components/landing/graphics/checklists-graphic.tsx new file mode 100644 index 0000000..4566100 --- /dev/null +++ b/apps/landing/src/components/landing/graphics/checklists-graphic.tsx @@ -0,0 +1,85 @@ +"use client"; + +import { motion } from "framer-motion"; +import { CheckSquareOffset, DotsSixVertical, Plus } from "@phosphor-icons/react"; + +export function ChecklistsGraphic() { + return ( +
+ {/* Background Dots */} +
+
+
+ + +
+
+

Onboarding Checklist

+

Target: New Signups

+
+
+ Active +
+
+ +
+ {[ + { title: "Complete Profile", desc: "Add your name and avatar", done: true, active: false }, + { title: "Invite Team Members", desc: "Invite at least 2 colleagues", done: false, active: true }, + { title: "Connect Integration", desc: "Link Slack or Linear", done: false, active: false }, + ].map((task, i) => ( + + + +
+ +
+ +
+
+ {task.title} +
+
{task.desc}
+ + {task.active && ( + + + Trigger: Tour Completed + + )} +
+ + ))} + + + Add Step + +
+ +
+ ); +} diff --git a/apps/landing/src/components/landing/graphics/knowledge-graphic.tsx b/apps/landing/src/components/landing/graphics/knowledge-graphic.tsx new file mode 100644 index 0000000..be326e2 --- /dev/null +++ b/apps/landing/src/components/landing/graphics/knowledge-graphic.tsx @@ -0,0 +1,105 @@ +"use client"; + +import { motion } from "framer-motion"; +import { BookOpenText, Folder, Article, MagnifyingGlass } from "@phosphor-icons/react"; + +export function KnowledgeBaseGraphic() { + return ( +
+ {/* Sidebar */} +
+
+ + Search articles... +
+ +
+
+ + Getting Started +
+
+
+
+ Installation Guide +
+
+
+ Quickstart Tutorial +
+
+
+ +
+
+ + API Reference +
+
+
+ + {/* Editor Area */} +
+ {/* Floating Toolbar */} + +
B
+
I
+
U
+
+
H1
+
H2
+ + +
+ + Installation Guide + + + +

+ Welcome to the Opencom installation guide. This document will walk you through setting up the core platform and integrating the frontend widgets. +

+ +
+
+ npm install @opencom/widget
+ npx opencom init +
+ +
+
+
+
+
+
+ +
+ + {/* Abstract Publish Button */} + + + Publish Article + +
+
+ ); +} diff --git a/apps/landing/src/components/landing/graphics/tooltips-graphic.tsx b/apps/landing/src/components/landing/graphics/tooltips-graphic.tsx new file mode 100644 index 0000000..f99b790 --- /dev/null +++ b/apps/landing/src/components/landing/graphics/tooltips-graphic.tsx @@ -0,0 +1,91 @@ +"use client"; + +import { motion } from "framer-motion"; +import { CursorClick, Info, CaretUp } from "@phosphor-icons/react"; + +export function TooltipsGraphic() { + return ( +
+ {/* Background Dashboard Mockup */} +
+
+
+
+
+
+
+
+
+
+ {[1, 2, 3, 4].map(i => ( +
+ ))} +
+
+
+ + {/* The Target Element */} +
+
+
+
+
+ + {/* Highlight Ring */} + + + {/* Tooltip Badge */} + + + + + {/* The Tooltip Popover */} + +
+ +
+

Configure API Keys

+

+ Generate your public and secret keys here to authenticate your backend requests. +

+ + +
+
+
+
+ + {/* Floating Cursor Interaction */} + + + + +
+ ); +} diff --git a/apps/landing/src/components/landing/graphics/widget-chat-graphic.tsx b/apps/landing/src/components/landing/graphics/widget-chat-graphic.tsx new file mode 100644 index 0000000..98b33aa --- /dev/null +++ b/apps/landing/src/components/landing/graphics/widget-chat-graphic.tsx @@ -0,0 +1,117 @@ +"use client"; + +import { motion } from "framer-motion"; +import { PaperPlaneRight, Robot, CaretLeft, Sparkle, Images } from "@phosphor-icons/react"; + +export function WidgetChatGraphic() { + return ( +
+ + {/* Chat Header */} +
+ +
+
+
+ +
+
+
+
+

AI Assistant

+

Typically replies instantly

+
+
+
+ + {/* Chat Messages */} +
+
+ + Today 10:42 AM + +
+ + +
+ How do I configure custom domains? +
+ Read + + + +
+ +
+
+

You can set up a custom domain in your workspace settings.

+
+
+ + Steps: +
+
    +
  1. Go to Settings > Domains
    2. +
  2. Click "Add Domain"
    3. +
  3. Configure your DNS records
    4. +
+
+
+ + + {/* Typing Indicator */} + +
+ +
+
+ + + +
+ +
+ + {/* Composer */} +
+
+ + + +
+
+ +
+ ); +} diff --git a/apps/landing/src/components/landing/graphics/widget-home-graphic.tsx b/apps/landing/src/components/landing/graphics/widget-home-graphic.tsx new file mode 100644 index 0000000..b2c6c81 --- /dev/null +++ b/apps/landing/src/components/landing/graphics/widget-home-graphic.tsx @@ -0,0 +1,93 @@ +"use client"; + +import { motion } from "framer-motion"; +import { House, Chats, Robot, BookOpenText, Megaphone, CaretRight } from "@phosphor-icons/react"; + +export function WidgetHomeGraphic() { + return ( +
+ + {/* Widget Header */} +
+
+
+
+
+
+

Hi there 👋

+

How can we help today?

+
+
+
+ + {/* Widget Body */} +
+ {/* Recent Conversation */} +
+
+ Recent conversation + +
+
+
+ S +
+
+

Yes, the Pro plan includes that.

+

Active 2h ago

+
+
+
+ + {/* Start New Action */} + + + {/* Quick Links Grid */} +
+
+
+ +
+ Help Center +
+
+
+ +
+ Ask AI Agent +
+
+
+ + {/* Widget Tab Bar */} +
+
+ + Home +
+
+ + Messages +
+
+ + Help +
+
+ + + News +
+
+ +
+ ); +} diff --git a/openspec/changes/launch-intercom-authority-distribution/.openspec.yaml b/openspec/changes/add-intercom-migration-wizard/.openspec.yaml similarity index 100% rename from openspec/changes/launch-intercom-authority-distribution/.openspec.yaml rename to openspec/changes/add-intercom-migration-wizard/.openspec.yaml diff --git a/openspec/changes/add-intercom-migration-wizard/design.md b/openspec/changes/add-intercom-migration-wizard/design.md new file mode 100644 index 0000000..c741478 --- /dev/null +++ b/openspec/changes/add-intercom-migration-wizard/design.md @@ -0,0 +1,117 @@ +## Context + +Opencom currently requires teams migrating from Intercom to assemble migration work manually across exports, field mapping, and verification. There is no single in-product flow that captures migration intent, validates readiness, executes long-running imports, and provides traceable completion evidence. + +This change spans multiple surfaces: +- `apps/web` for wizard setup, readiness review, run monitoring, and completion summary. +- `packages/convex` for migration plan persistence, preflight analysis, and long-running import orchestration. +- Intercom integration adapters for source reads, pagination, and normalized entity mapping into Opencom models. + +The most important constraints are reliability (no duplicate imports on retry), visibility (clear progress and errors), and safety (imports should not start when blocking issues exist). + +## Goals / Non-Goals + +**Goals:** +- Provide an end-to-end wizard for Intercom migration setup and execution. +- Make import readiness explicit via blocking error and warning classification. +- Run imports as resumable jobs with observable progress and actionable failure logs. +- Provide a completion summary and verification checklist before production cutover. + +**Non-Goals:** +- Achieving full parity for every Intercom object type in the first release. +- Building continuous bidirectional sync between Intercom and Opencom. +- Migrating unrelated operational concerns (for example billing history or external BI datasets). + +## Decisions + +### 1) Split migration into plan phase and run phase + +Decision: +- Persist a migration plan draft before execution, then create an immutable run record when import starts. + +Rationale: +- Separating setup from execution allows preflight validation and approval without starting side effects. +- Immutable run records make retries and audit trails clearer. + +Alternatives considered: +- Single write-once "start migration now" endpoint: rejected because it conflates setup errors with run-time failures and weakens resume behavior. + +### 2) Implement preflight as a deterministic rule engine with severity levels + +Decision: +- Preflight evaluates selected scope and mappings using explicit validation rules and emits findings classified as `blocking` or `warning`. + +Rationale: +- Deterministic severity output gives predictable operator behavior and straightforward testability. +- Severity-based gating maps directly to UX controls (disable start vs allow with acknowledgement). + +Alternatives considered: +- Best-effort import with no preflight gate: rejected because late failures increase migration risk and support load. + +### 3) Execute imports with checkpointed, idempotent workers + +Decision: +- Import jobs process each selected domain in bounded batches, persisting checkpoints and idempotency keys for each batch. + +Rationale: +- Checkpoints enable resume after interruption without replaying successful work. +- Batch-level idempotency prevents duplicate entities when retries overlap with partial completion. + +Alternatives considered: +- One-shot synchronous import request: rejected due to timeout risk, poor observability, and no practical recovery path. + +### 4) Store structured run events and error buckets for operator debugging + +Decision: +- Persist run events and domain-scoped error buckets (category, sample identifiers, reason, remediation hint) as first-class migration records. + +Rationale: +- Structured data is easier to filter in UI and easier to aggregate for reliability improvements. +- Error bucket summaries reduce operator time compared with raw per-record logs only. + +Alternatives considered: +- Raw log stream only: rejected because it is hard to interpret and hard to connect to remediation actions. + +### 5) Gate initial release behind a feature flag and scoped access control + +Decision: +- Ship behind a workspace feature flag and restrict migration run actions to admins. + +Rationale: +- Controlled rollout lowers blast radius while we validate performance and mapping coverage. +- Admin-only run permissions reduce accidental imports during early adoption. + +Alternatives considered: +- Immediate general availability: rejected because migration quality and support volume are still unknown in production workloads. + +## Risks / Trade-offs + +- [Risk] Intercom API rate limits can stretch migration duration. + - Mitigation: adaptive backoff, domain-level batching, and user-visible ETA confidence bands. +- [Risk] Mapping mismatch can cause partial import quality issues. + - Mitigation: strict blocking validations for required identities and explicit warning acknowledgement for lossy fields. +- [Risk] Resume logic complexity may introduce duplicate or skipped records. + - Mitigation: checkpoint integrity tests, idempotency keys, and run-level reconciliation counters. +- [Risk] Large conversation/help-center datasets can generate noisy failure logs. + - Mitigation: bucketized error summaries with downloadable detailed samples. + +## Migration Plan + +1. Add migration domain models and persistence primitives for drafts, preflight outputs, runs, checkpoints, and run events. +2. Implement Intercom source adapters and normalization pipeline for first-release supported domains. +3. Implement preflight rule engine and readiness-report API surface. +4. Implement migration job runner with checkpointing, retry, and idempotency protections. +5. Implement web wizard flow: setup, readiness review, run monitor, and completion checklist. +6. Enable internal testing with feature flag, run seeded test migrations, and tune retry/error UX. +7. Roll out to limited beta workspaces, monitor success/failure metrics, then expand availability. + +Rollback strategy: +- Disable the migration feature flag for all workspaces. +- Stop new run creation while allowing existing in-flight runs to complete or be marked failed safely. +- Retain persisted run artifacts for audit and support-led recovery. + +## Open Questions + +- Which Intercom authentication mechanism should be primary for v1 (OAuth app install vs admin token input)? +- What maximum source dataset size should be supported before requiring staged imports by domain? +- Should completion checklist sign-off be stored as an auditable event with user identity and timestamp? diff --git a/openspec/changes/add-intercom-migration-wizard/proposal.md b/openspec/changes/add-intercom-migration-wizard/proposal.md new file mode 100644 index 0000000..c96dcdd --- /dev/null +++ b/openspec/changes/add-intercom-migration-wizard/proposal.md @@ -0,0 +1,35 @@ +## Why + +Teams switching from Intercom to Opencom still face high migration friction: they must manually export data, map fields, and validate what will or will not transfer before going live. That uncertainty slows down conversions and onboarding, so we need a guided migration path that makes switching predictable and low risk. + +## What Changes + +- Add an in-product Intercom migration wizard that guides teams from connection to import completion. +- Add a step-by-step flow for: + - connecting an Intercom workspace, + - selecting migration scope (for example contacts, companies, conversations, help center content), + - mapping required fields and identities, + - running a preflight check before import, + - executing import with clear progress visibility. +- Add compatibility reporting that flags unsupported Intercom objects/features and provides explicit fallback guidance. +- Add resumable migration jobs with retry handling, import logs, and actionable error states. +- Add a post-migration verification checklist and completion summary so teams can confirm readiness before switching traffic. + +## Capabilities + +### New Capabilities + +- `intercom-migration-wizard-flow`: Opencom provides a guided, multi-step wizard to connect Intercom and complete migration setup end to end. +- `intercom-migration-readiness-reporting`: Opencom provides preflight compatibility and validation output so teams know migration risk before import. +- `intercom-migration-job-tracking-and-recovery`: Opencom runs migration imports as observable, resumable jobs with progress, error details, and retry paths. + +### Modified Capabilities + +- None. + +## Impact + +- Web app onboarding/settings UI for migration setup, progress, and completion states. +- Backend migration services/jobs, import orchestration, and persistence for mapping/validation/run history. +- Integration layer for Intercom API access and data normalization into Opencom domain models. +- QA scope across happy path, partial failures, resume/retry behavior, and post-migration verification. diff --git a/openspec/changes/add-intercom-migration-wizard/specs/intercom-migration-job-tracking-and-recovery/spec.md b/openspec/changes/add-intercom-migration-wizard/specs/intercom-migration-job-tracking-and-recovery/spec.md new file mode 100644 index 0000000..2a05adb --- /dev/null +++ b/openspec/changes/add-intercom-migration-wizard/specs/intercom-migration-job-tracking-and-recovery/spec.md @@ -0,0 +1,35 @@ +## ADDED Requirements + +### Requirement: Migration imports MUST run as observable asynchronous jobs +Opencom SHALL execute migration imports as asynchronous jobs with lifecycle states and progress metrics visible to admins. + +#### Scenario: Admin tracks active import progress +- **WHEN** a migration job is running +- **THEN** the job status view SHALL show current lifecycle state, percentage progress, and domain-level processed counts +- **AND** progress updates SHALL be visible without restarting the migration flow + +#### Scenario: Admin views terminal job outcome +- **WHEN** a migration job reaches completed or failed status +- **THEN** the job status view SHALL show final imported, skipped, and failed counts by selected domain +- **AND** the outcome SHALL include the completion timestamp + +### Requirement: Migration jobs MUST support checkpoint-based resume and retry +Opencom SHALL support resuming failed or interrupted migration jobs from the last durable checkpoint without duplicating already imported records. + +#### Scenario: Retry resumes after interruption +- **WHEN** a migration job fails due to a transient error after partial import +- **THEN** an admin-triggered retry SHALL resume from the latest persisted checkpoint +- **AND** previously completed checkpoints SHALL NOT be re-imported + +#### Scenario: Retry is blocked until blocking cause is fixed +- **WHEN** a failed migration has unresolved blocking configuration errors +- **THEN** the retry action SHALL be disabled +- **AND** the job detail SHALL show the blocking error categories that must be resolved + +### Requirement: Migration jobs MUST expose actionable error logs +For failed or partially failed migrations, Opencom SHALL provide structured error logs that identify where failures occurred and what corrective action is recommended. + +#### Scenario: Admin investigates failed records +- **WHEN** an admin opens a failed migration job detail +- **THEN** the system SHALL provide domain-specific error buckets with sample record identifiers and failure reasons +- **AND** each error bucket SHALL include recommended remediation guidance before retry diff --git a/openspec/changes/add-intercom-migration-wizard/specs/intercom-migration-readiness-reporting/spec.md b/openspec/changes/add-intercom-migration-wizard/specs/intercom-migration-readiness-reporting/spec.md new file mode 100644 index 0000000..3603383 --- /dev/null +++ b/openspec/changes/add-intercom-migration-wizard/specs/intercom-migration-readiness-reporting/spec.md @@ -0,0 +1,30 @@ +## ADDED Requirements + +### Requirement: Readiness report MUST validate migration prerequisites before import +Opencom SHALL run a preflight validation pass before import start and produce a readiness report that classifies findings as blocking errors or non-blocking warnings. + +#### Scenario: Blocking validation failure prevents import +- **WHEN** preflight detects missing required mappings or missing source permissions +- **THEN** the readiness report SHALL classify those findings as blocking errors +- **AND** the wizard SHALL disable import start until all blocking errors are resolved + +#### Scenario: Non-blocking warnings allow import with acknowledgement +- **WHEN** preflight detects warning-level issues that do not prevent import +- **THEN** the readiness report SHALL list each warning with impact context +- **AND** the admin SHALL be able to continue only after explicitly acknowledging warnings + +### Requirement: Readiness report MUST identify unsupported Intercom features with fallback guidance +If the selected source workspace includes unsupported Intercom objects or feature constructs, the readiness report SHALL identify each unsupported item and provide a recommended fallback path. + +#### Scenario: Unsupported feature is detected +- **WHEN** preflight finds an unsupported source feature in selected migration scope +- **THEN** the readiness report SHALL list the feature name and affected records count +- **AND** the report SHALL include an explicit fallback action (for example manual recreation or alternative Opencom primitive) + +### Requirement: Readiness report MUST provide an auditable summary for sign-off +Opencom SHALL preserve a timestamped readiness summary for each migration attempt so teams can review what risks were accepted before import start. + +#### Scenario: Admin reviews readiness before running import +- **WHEN** an admin opens the review step after preflight completes +- **THEN** the wizard SHALL show totals for blocking errors, warnings, and ready entities by selected domain +- **AND** the system SHALL store the final readiness summary linked to the eventual migration job diff --git a/openspec/changes/add-intercom-migration-wizard/specs/intercom-migration-wizard-flow/spec.md b/openspec/changes/add-intercom-migration-wizard/specs/intercom-migration-wizard-flow/spec.md new file mode 100644 index 0000000..e73d129 --- /dev/null +++ b/openspec/changes/add-intercom-migration-wizard/specs/intercom-migration-wizard-flow/spec.md @@ -0,0 +1,35 @@ +## ADDED Requirements + +### Requirement: Migration wizard MUST enforce a deterministic setup sequence +Opencom SHALL provide a multi-step Intercom migration wizard that enforces this ordered sequence: connect workspace, choose migration scope, map required identities/fields, review preflight results, and start import. + +#### Scenario: Admin completes setup in required order +- **WHEN** a workspace admin starts an Intercom migration +- **THEN** the wizard SHALL display each setup step in the required order +- **AND** the admin SHALL NOT advance past a step until its required inputs pass validation + +#### Scenario: Wizard restores in-progress setup +- **WHEN** a workspace admin exits the wizard before starting import and returns later +- **THEN** the wizard SHALL restore previously saved scope and mapping selections +- **AND** the wizard SHALL reopen at the next incomplete step + +### Requirement: Migration wizard MUST support explicit migration scope selection +The wizard SHALL let admins explicitly include or exclude supported Intercom data domains (for example contacts, companies, conversations, and help center content) before import begins. + +#### Scenario: Admin selects subset migration +- **WHEN** the admin selects only a subset of supported domains in scope selection +- **THEN** the migration plan SHALL include only the selected domains +- **AND** the review step SHALL show excluded domains as excluded by user choice + +#### Scenario: Scope change invalidates stale mappings +- **WHEN** the admin removes a previously selected data domain from scope +- **THEN** mappings tied only to that domain SHALL be removed from the draft plan +- **AND** the wizard SHALL require a fresh readiness review before import can start + +### Requirement: Migration wizard MUST produce a completion summary with verification checklist +After import completion, Opencom SHALL present a migration completion summary and a checklist of verification steps required before production cutover. + +#### Scenario: Import completes successfully +- **WHEN** the migration job reaches completed status +- **THEN** the wizard SHALL show imported record counts by selected domain +- **AND** the completion view SHALL include a checklist covering data spot checks, routing/automation validation, and team handoff confirmation diff --git a/openspec/changes/add-intercom-migration-wizard/tasks.md b/openspec/changes/add-intercom-migration-wizard/tasks.md new file mode 100644 index 0000000..44522c4 --- /dev/null +++ b/openspec/changes/add-intercom-migration-wizard/tasks.md @@ -0,0 +1,35 @@ +## 1. Migration Domain And Integration Foundations + +- [ ] 1.1 Add migration persistence models for drafts, readiness reports, runs, checkpoints, and run events. +- [ ] 1.2 Implement Intercom source client/auth handling with pagination, rate-limit backoff, and scoped data fetch APIs. +- [ ] 1.3 Implement normalization/mapping primitives for supported v1 domains (contacts, companies, conversations, help center content). + +## 2. Wizard Setup Flow + +- [ ] 2.1 Implement migration wizard state machine and server-backed draft persistence/resume behavior. +- [ ] 2.2 Build wizard UI steps for source connection, scope selection, required mapping, and review. +- [ ] 2.3 Enforce step-level validation gates so import cannot start until required setup fields are valid. + +## 3. Readiness Reporting + +- [ ] 3.1 Implement preflight rule engine with deterministic `blocking` and `warning` severity outputs. +- [ ] 3.2 Implement unsupported Intercom feature detection with per-feature fallback guidance in readiness output. +- [ ] 3.3 Add readiness acknowledgement flow that blocks import on unresolved errors and requires warning acknowledgement. + +## 4. Job Execution, Tracking, And Recovery + +- [ ] 4.1 Implement asynchronous migration job runner with lifecycle states and domain-level progress counters. +- [ ] 4.2 Implement checkpointed resume + retry with idempotency protections to prevent duplicate imports. +- [ ] 4.3 Implement structured failure/error buckets with remediation hints and sample record references. + +## 5. Completion Experience And Guardrails + +- [ ] 5.1 Implement completion summary view with imported/skipped/failed counts by selected domain. +- [ ] 5.2 Implement post-migration verification checklist and persist sign-off metadata for auditability. +- [ ] 5.3 Gate migration run actions behind workspace feature flag and admin-only authorization checks. + +## 6. Verification + +- [ ] 6.1 Add unit tests for setup-step gating, scope/mapping invalidation, and preflight severity classification. +- [ ] 6.2 Add integration tests for checkpoint resume, retry behavior, and duplicate-import prevention. +- [ ] 6.3 Run focused package checks (typecheck/tests for touched packages) and strict `openspec validate add-intercom-migration-wizard --strict --no-interactive`. diff --git a/openspec/changes/persist-full-ai-response-on-handoff/.openspec.yaml b/openspec/changes/archive/2026-03-04-persist-full-ai-response-on-handoff/.openspec.yaml similarity index 100% rename from openspec/changes/persist-full-ai-response-on-handoff/.openspec.yaml rename to openspec/changes/archive/2026-03-04-persist-full-ai-response-on-handoff/.openspec.yaml diff --git a/openspec/changes/persist-full-ai-response-on-handoff/design.md b/openspec/changes/archive/2026-03-04-persist-full-ai-response-on-handoff/design.md similarity index 100% rename from openspec/changes/persist-full-ai-response-on-handoff/design.md rename to openspec/changes/archive/2026-03-04-persist-full-ai-response-on-handoff/design.md diff --git a/openspec/changes/persist-full-ai-response-on-handoff/proposal.md b/openspec/changes/archive/2026-03-04-persist-full-ai-response-on-handoff/proposal.md similarity index 100% rename from openspec/changes/persist-full-ai-response-on-handoff/proposal.md rename to openspec/changes/archive/2026-03-04-persist-full-ai-response-on-handoff/proposal.md diff --git a/openspec/changes/persist-full-ai-response-on-handoff/specs/ai-handoff-response-traceability/spec.md b/openspec/changes/archive/2026-03-04-persist-full-ai-response-on-handoff/specs/ai-handoff-response-traceability/spec.md similarity index 100% rename from openspec/changes/persist-full-ai-response-on-handoff/specs/ai-handoff-response-traceability/spec.md rename to openspec/changes/archive/2026-03-04-persist-full-ai-response-on-handoff/specs/ai-handoff-response-traceability/spec.md diff --git a/openspec/changes/persist-full-ai-response-on-handoff/tasks.md b/openspec/changes/archive/2026-03-04-persist-full-ai-response-on-handoff/tasks.md similarity index 100% rename from openspec/changes/persist-full-ai-response-on-handoff/tasks.md rename to openspec/changes/archive/2026-03-04-persist-full-ai-response-on-handoff/tasks.md diff --git a/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/design.md b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/design.md index a01aae4..1b57ffa 100644 --- a/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/design.md +++ b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/design.md @@ -1,70 +1,158 @@ ## Context Current docs and package state are inconsistent: docs claim npm installation while package metadata and dependency graph are not publish-ready. Without a release pipeline, versioning and distribution remain manual and error-prone. +The current change was mobile-centric, but release concerns are portfolio-wide: we need one coherent strategy for all externally consumed packages (mobile SDK plus other framework-facing/shared packages where sensible), including branching, SemVer support policy, and backend compatibility governance. ## Goals / Non-Goals **Goals:** -- Make the mobile SDK installable from a supported registry. +- Define a portfolio-wide model for which packages are public vs internal. +- Make all approved public packages installable from supported registries. - Ensure transitive dependencies are resolvable outside the monorepo. -- Automate build/test/version/publish release flow. -- Align docs with real distribution and installation paths. +- Automate multi-package version/build/test/publish flow. +- Define release governance (branching, tags, channels, support windows, deprecations). +- Protect existing npm consumers through explicit backward-compatibility policy. +- Define Convex backend contract versioning and compatibility checks for published packages that rely on backend contracts. +- Align docs with real distribution and installation paths across supported consumer surfaces. **Non-Goals:** -- Publishing every monorepo package in this change. -- Redesigning SDK public API. +- Publishing every monorepo package by default. +- Redesigning SDK public APIs as part of release-process work. ## Decisions -### 1) Define an explicit publishable package set and dependency policy +### 1) Define a public package portfolio and ownership model Decision: -- Publish the minimum required package set for external SDK consumption and eliminate unresolved `workspace:*` dependencies in published artifacts. +- Maintain an explicit portfolio inventory that classifies packages as: + - public-supported (intended for external npm consumers), + - public-experimental (opt-in prerelease channel), + - internal-only (private). +- Only portfolio-approved public packages are included in publish automation. Rationale: -- External consumers must resolve all dependencies from registry-compatible versions. +- Prevents accidental publication of internal packages and makes support commitments explicit. Alternatives considered: -- Publish only the top-level package while keeping unresolved workspace dependencies. Rejected because installs fail. +- Keep ad-hoc per-package publication decisions. Rejected because it causes drift and unclear ownership. -### 2) Use automated versioning + publish workflow +### 2) Enforce dependency boundaries for publishable packages Decision: -- Implement a release workflow that performs versioning, changelog generation, build/typecheck/tests, and registry publish in one controlled pipeline. +- Public packages MUST NOT rely on unresolved `workspace:*` dependencies at publish time. +- Public package manifests MUST declare registry-resolvable dependencies, stable exports, and explicit publish surface (`files`, `exports`, peer dependency ranges). +- Where a public package depends on shared internal logic, that logic must be moved into publishable shared packages or removed from public runtime paths. Rationale: -- Reduces manual release errors and keeps docs/versioning in sync. +- External consumers need deterministic installs without monorepo internals. Alternatives considered: -- Manual publish commands. Rejected due to repeatability and auditability concerns. +- Publish only top-level packages while leaving workspace-only transitives. Rejected because installs break. -### 3) Add publish smoke validation +### 3) Use automated multi-package versioning and publish orchestration Decision: -- Add a smoke step that validates package tarball installability in a clean environment before publish. +- Implement release automation that: + - detects changed public packages, + - includes affected dependent public packages when required, + - versions and publishes in dependency-safe order, + - records changelog/release notes per published package. Rationale: -- Catches missing files/invalid dependency metadata early. +- Keeps multi-package releases consistent and reduces manual sequencing errors. + +Alternatives considered: +- Manual publish commands per package. Rejected due to repeatability and auditability concerns. + +### 4) Release from `main` by tag; avoid a permanent release branch + +Decision: +- Use trunk-based releases: cut public package releases from `main` using semver tags. +- Do not require a long-lived `release` branch. +- Allow short-lived `release/x.y` branches only for backport/hotfix cases for older supported lines. + +Rationale: +- Matches existing production deployment practices and minimizes branch drift. + +Alternatives considered: +- Always release from a long-lived `release` branch. Rejected due to overhead and delayed fixes. + +### 5) Enforce npm backward compatibility via SemVer + dist-tags + support windows + +Decision: +- Adopt strict SemVer for all public packages: + - patch/minor releases MUST remain backwards-compatible within a major line, + - breaking changes REQUIRE a major bump. +- Use dist-tags intentionally: + - `latest` for stable releases, + - `next` (or equivalent) for prerelease/experimental channels. +- Define support policy: + - maintain at least current and previous major lines for critical fixes for a documented window, + - publish migration notes before and during major cutovers. + +Rationale: +- Protects slower-moving consumers while enabling safe iteration. + +Alternatives considered: +- Single rolling `latest` with no support policy. Rejected due to upgrade risk. + +### 6) Version Convex compatibility explicitly across public packages + +Decision: +- Treat package-to-Convex compatibility as a first-class contract: + - define backend contract/version metadata discoverable by consumers, + - define per-package supported backend contract range, + - add release-time validation against minimum and current supported backend contract versions. +- For breaking backend contract changes impacting public packages: + - ship compatibility adapters when feasible within current major lines, or + - coordinate major package releases with migration guidance. + +Rationale: +- Prevents silent runtime breakage when consumer app/package version and backend deployment version are skewed. + +Alternatives considered: +- Implicit compatibility with no explicit contract range. Rejected because failures are late and hard to debug. + +### 7) Add portfolio-aware publish smoke validation + +Decision: +- Add smoke checks that install and minimally execute published tarballs in clean consumer fixtures for each supported package type (for example React Native and Next.js where applicable). + +Rationale: +- Catches missing files, invalid metadata, and framework-specific integration regressions before publish. ## Risks / Trade-offs -- [Risk] Changing package metadata can impact monorepo local workflows. - - Mitigation: keep internal development path unchanged; validate both workspace and published paths. +- [Risk] Wider scope increases implementation complexity and timeline. + - Mitigation: phase rollout by package cohort with explicit acceptance gates. +- [Risk] Package boundary refactors may disrupt local monorepo workflows. + - Mitigation: validate both workspace development path and published-consumer path in CI. - [Risk] Registry auth/provenance misconfiguration blocks release. - - Mitigation: add staged dry-run workflow and explicit secret checks. + - Mitigation: staged dry-run workflow and explicit secret checks. +- [Risk] Breaking changes may leak into minor/patch releases. + - Mitigation: SemVer policy checks and compatibility test gates. +- [Risk] Public package versions may drift from backend capability assumptions. + - Mitigation: explicit backend contract ranges and release matrix validation. ## Migration Plan -1. Define publishable package matrix and dependency resolution strategy. -2. Update package manifests for publish readiness. -3. Implement release automation workflow and secrets/provenance configuration. -4. Run dry-run publish and smoke install in CI. -5. Update docs and release runbook with final install instructions. +1. Inventory candidate public packages and classify each (supported, experimental, internal). +2. Define dependency boundary changes needed for publishability. +3. Update package manifests and dependency graph for approved public packages. +4. Define release governance policy (branching, tags, SemVer, dist-tags, support windows). +5. Define Convex compatibility metadata and per-package contract-range rules. +6. Implement multi-package release automation with dependency-aware publish ordering. +7. Add smoke/integration compatibility validation across relevant consumer fixtures. +8. Run dry-run releases, then stage initial public package cohort rollout. +9. Update docs/runbooks with package matrix, install paths, support, and migration guidance. Rollback: -- Disable publish workflow and revert package metadata changes if release validation fails. +- Suspend publish workflow for failing package cohorts while keeping unaffected cohorts disabled from release triggers. +- Repoint dist-tags to last known-good versions and pause new publishes until compatibility gates pass. ## Open Questions -- Should npm be primary and GitHub Packages fallback, or vice versa? -- Do we require signed provenance attestations for initial public releases? +- Which additional framework-facing packages (for example Next.js integration) are in the first public-supported cohort? +- Should npm be primary with GitHub Packages fallback, or dual-publish from day one? +- Should Convex-generated contracts be exposed via a dedicated public contract package, or via stable facades in each consumer package? +- Do we require signed provenance attestations for initial public releases or after first stable cohort? diff --git a/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/proposal.md b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/proposal.md index 0d272eb..c46652a 100644 --- a/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/proposal.md +++ b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/proposal.md @@ -1,19 +1,31 @@ ## Why The React Native SDK package is still marked `private` and depends on workspace-only packages, while docs already instruct external installation via `@opencom/react-native-sdk`. There is no release pipeline for SDK packages and npm registry lookups currently return not found, so install guidance is not actionable. +The same planning gap applies to other potential externally consumed packages (for example shared SDK modules and framework adapters such as Next.js): we do not yet have a portfolio-wide publish policy, release governance model, or explicit backend compatibility contract strategy. ## What Changes -- Define and implement a publishable package graph for mobile SDK distribution (npm and/or GitHub Packages) including all required transitive dependencies. +- Define a portfolio-wide package classification model: + - which packages are public/installable from npm, + - which remain internal/private, + - and publish ordering/dependency rules across public packages. +- Define and implement a publishable package graph for all approved public consumer packages (including mobile SDK and framework-facing packages where sensible) with resolvable transitive dependencies. - Remove workspace-only dependency blockers from publishable packages (or publish required internal dependencies). -- Create a versioned release pipeline that builds, verifies, and publishes SDK artifacts. -- Update Mobile SDK installation docs to match actual distribution and release process. +- Define release governance for public package delivery: + - git strategy for releases (default trunk/tag release, with scoped maintenance branches only when needed), + - semantic versioning and npm dist-tag policy for backwards compatibility, + - support windows and deprecation policy for older major lines. +- Define Convex backend contract versioning and compatibility guarantees for published packages that depend on backend-generated APIs/contracts. +- Create a versioned release pipeline that builds, verifies, and publishes changed public package artifacts under this governance model. +- Update installation docs and release runbook to match actual package distribution and compatibility process across supported consumer surfaces. ## Capabilities ### New Capabilities -- `mobile-sdk-package-distribution`: Mobile SDK packages are publishable/installable from configured package registries with automated release workflow. +- `public-package-portfolio-distribution`: Approved public packages are publishable/installable from configured registries with resolvable dependencies. +- `public-package-release-governance`: Public package releases follow explicit branching/tagging, SemVer, dist-tag, and support-window policies. +- `public-package-convex-compatibility`: Published packages that rely on Convex contracts declare and validate backend compatibility ranges. ### Modified Capabilities @@ -21,6 +33,8 @@ The React Native SDK package is still marked `private` and depends on workspace- ## Impact -- Package manifests for mobile SDK and required dependencies (`private`, `publishConfig`, dependency versions). -- CI/workflow automation for release and publish. -- Mobile SDK installation docs and release runbook. +- Package manifests across selected public packages (`private`, versioning strategy, `publishConfig`, files/exports, dependency versions). +- CI/workflow automation for changed-package detection, ordered publish, and compatibility gates. +- Release governance docs for branching, tagging, npm dist-tags, support windows, and deprecation timelines. +- Convex compatibility contract metadata and validation rules used by release checks. +- Installation docs and release runbook for mobile and other supported consumer package entry points. diff --git a/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/mobile-sdk-package-distribution/spec.md b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/mobile-sdk-package-distribution/spec.md deleted file mode 100644 index 62d2113..0000000 --- a/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/mobile-sdk-package-distribution/spec.md +++ /dev/null @@ -1,29 +0,0 @@ -## ADDED Requirements - -### Requirement: Mobile SDK distribution MUST provide registry-installable packages with resolvable dependencies - -Published mobile SDK packages SHALL be installable from supported registries with fully resolvable transitive dependencies. - -#### Scenario: Consumer installs SDK in external project - -- **WHEN** a consumer runs the documented SDK install command in a non-monorepo project -- **THEN** dependency resolution SHALL succeed without unresolved workspace protocol references - -### Requirement: Release pipeline MUST automate versioned SDK publication - -The release pipeline SHALL perform versioning, quality checks, build, and publish for configured mobile SDK packages. - -#### Scenario: Release pipeline runs for a tagged release - -- **WHEN** a release is triggered for SDK packages -- **THEN** the pipeline SHALL run required quality/build checks -- **AND** publish versioned artifacts to configured registry targets on success - -### Requirement: Installation documentation MUST match published distribution reality - -Mobile SDK documentation SHALL describe the currently supported install commands and registry configuration requirements. - -#### Scenario: New consumer follows docs - -- **WHEN** a developer follows the documented installation flow -- **THEN** they SHALL be able to install and import the SDK successfully diff --git a/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/public-package-convex-compatibility/spec.md b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/public-package-convex-compatibility/spec.md new file mode 100644 index 0000000..7250415 --- /dev/null +++ b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/public-package-convex-compatibility/spec.md @@ -0,0 +1,30 @@ +## ADDED Requirements + +### Requirement: Public packages using Convex contracts MUST declare compatibility ranges + +Any published public package that relies on Convex backend contracts SHALL declare its supported backend contract version range. + +#### Scenario: Package release preparation includes Convex-dependent package + +- **WHEN** maintainers prepare a release for a package that depends on Convex contracts +- **THEN** release metadata SHALL include minimum and maximum supported backend contract versions (or equivalent compatible range) + +### Requirement: Release validation MUST check Convex compatibility matrix + +Release automation SHALL validate Convex-dependent public packages against the documented supported backend contract range. + +#### Scenario: Release validation runs for Convex-dependent package + +- **WHEN** release checks run +- **THEN** validation SHALL exercise compatibility against minimum and current supported backend contract versions +- **AND** release SHALL fail if compatibility checks do not pass + +### Requirement: Runtime incompatibility MUST fail deterministically with guidance + +When a consumer uses a package with an unsupported backend contract version, the package SHALL surface an explicit compatibility failure. + +#### Scenario: Consumer app initializes against unsupported backend contract + +- **WHEN** package initialization detects backend contract version outside supported range +- **THEN** the package SHALL return a deterministic compatibility error with actionable upgrade guidance +- **AND** the error SHALL be distinguishable from transient network or authentication failures diff --git a/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/public-package-portfolio-distribution/spec.md b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/public-package-portfolio-distribution/spec.md new file mode 100644 index 0000000..69edeae --- /dev/null +++ b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/public-package-portfolio-distribution/spec.md @@ -0,0 +1,30 @@ +## ADDED Requirements + +### Requirement: Public package portfolio MUST define publish scope explicitly + +The release system SHALL maintain an explicit inventory of packages classified as public-supported, public-experimental, or internal-only. + +#### Scenario: Maintainer evaluates package for publication + +- **WHEN** a package is considered for npm publication +- **THEN** the package SHALL be classified in the portfolio inventory before release automation can publish it +- **AND** classification SHALL include ownership and support expectation + +### Requirement: Public packages MUST be registry-installable with resolvable dependencies + +Published public packages SHALL be installable in external projects with fully resolvable transitive dependencies. + +#### Scenario: Consumer installs a published package in a non-monorepo project + +- **WHEN** a consumer runs the documented install command +- **THEN** dependency resolution SHALL succeed without unresolved workspace protocol references +- **AND** package exports/files metadata SHALL resolve correctly in the consumer runtime + +### Requirement: Distribution docs MUST match approved package portfolio + +Installation and usage documentation SHALL reflect the currently approved public package set and supported consumer frameworks. + +#### Scenario: New consumer follows framework-specific docs + +- **WHEN** a developer follows docs for a supported package and framework path +- **THEN** they SHALL be able to install, import, and run the documented quick start successfully diff --git a/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/public-package-release-governance/spec.md b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/public-package-release-governance/spec.md new file mode 100644 index 0000000..08987ca --- /dev/null +++ b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/specs/public-package-release-governance/spec.md @@ -0,0 +1,51 @@ +## ADDED Requirements + +### Requirement: Release process MUST define git branching and tagging policy + +Public package release governance SHALL define a default release path from `main` via version tags and SHALL define when maintenance branches are allowed. + +#### Scenario: Standard public package release + +- **WHEN** a normal release is prepared +- **THEN** release automation SHALL publish from `main` using semver release tags +- **AND** a long-lived `release` branch SHALL NOT be required for standard releases + +#### Scenario: Backport fix for an older supported line + +- **WHEN** maintainers must patch an older supported major/minor line +- **THEN** maintainers MAY create a scoped `release/x.y` maintenance branch for that backport +- **AND** the backport flow SHALL NOT alter standard `main` release behavior + +### Requirement: Release pipeline MUST automate multi-package publication safely + +The release pipeline SHALL run quality checks, versioning, and publish steps for changed public packages in dependency-safe order. + +#### Scenario: Tagged release includes multiple public packages + +- **WHEN** a release includes package changes affecting more than one public package +- **THEN** the pipeline SHALL detect affected packages +- **AND** publish packages in dependency-safe order +- **AND** fail the release if required quality or publishability gates do not pass + +### Requirement: Public package versions MUST preserve backward compatibility expectations + +Published public packages SHALL follow SemVer and dist-tag rules that protect older consumers. + +#### Scenario: Non-breaking package changes + +- **WHEN** a release contains only backward-compatible changes +- **THEN** maintainers SHALL publish patch/minor versions within the current major line +- **AND** consumers on that major line SHALL NOT require migration changes + +#### Scenario: Breaking package changes + +- **WHEN** a release introduces breaking API or behavior changes +- **THEN** maintainers SHALL publish a new major version +- **AND** release notes SHALL include migration guidance +- **AND** older supported major lines SHALL remain available according to documented support policy + +#### Scenario: Prerelease channel use + +- **WHEN** maintainers publish prerelease builds +- **THEN** prereleases SHALL use a non-`latest` dist-tag +- **AND** `latest` consumers SHALL NOT be upgraded to prerelease versions implicitly diff --git a/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/tasks.md b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/tasks.md index 0956dcb..aeb490f 100644 --- a/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/tasks.md +++ b/openspec/changes/publish-mobile-sdk-packages-and-release-pipeline/tasks.md @@ -1,19 +1,44 @@ -## 1. Publishability Planning +## 1. Public Package Portfolio Definition -- [ ] 1.1 Define publishable SDK package set and dependency resolution strategy. -- [ ] 1.2 Identify and remove/replace workspace-only dependencies in published artifacts. +- [ ] 1.1 Create portfolio inventory for candidate packages (public-supported, public-experimental, internal-only). +- [ ] 1.2 Define package ownership and support commitments for each public-supported package. +- [ ] 1.3 Decide first rollout cohort (mobile SDK plus other framework-facing/shared packages where sensible). -## 2. Package Metadata Updates +## 2. Publishability And Dependency Boundary Planning -- [ ] 2.1 Update package manifests (`private`, versioning strategy, `publishConfig`, files/exports) for publish-ready packages. -- [ ] 2.2 Ensure transitive dependency versions are registry-resolvable. +- [ ] 2.1 Define dependency resolution strategy for each public package in the first cohort. +- [ ] 2.2 Identify and remove/replace workspace-only dependencies from publishable runtime paths. +- [ ] 2.3 Define publish order/topology for interdependent public packages. -## 3. Release Automation +## 3. Package Metadata Updates -- [ ] 3.1 Implement CI workflow for versioning, build/type/test checks, and publish. -- [ ] 3.2 Add dry-run/smoke-install validation before publish steps. +- [ ] 3.1 Update package manifests (`private`, versioning strategy, `publishConfig`, files/exports, peer dependency ranges) for publish-ready packages. +- [ ] 3.2 Ensure transitive dependency versions are registry-resolvable. +- [ ] 3.3 Add package-level metadata for support tier and release channel eligibility where required. -## 4. Documentation And Validation +## 4. Release Governance Definition -- [ ] 4.1 Update mobile SDK install docs and release runbook to match final distribution path. -- [ ] 4.2 Validate installation in a clean consumer project flow. +- [ ] 4.1 Define git release policy (default tag-from-`main`, with `release/x.y` maintenance branches only for backports). +- [ ] 4.2 Define SemVer rules, npm dist-tag usage (`latest` vs `next`), and support window for older major lines. +- [ ] 4.3 Define deprecation and end-of-support policy for older package lines. + +## 5. Convex Compatibility Governance + +- [ ] 5.1 Define Convex compatibility contract/versioning policy for public packages that depend on backend contracts. +- [ ] 5.2 Define compatibility range metadata format and where it is surfaced (release artifacts/runtime metadata). +- [ ] 5.3 Define migration playbook for backend contract breaking changes (adapter vs coordinated major release). + +## 6. Release Automation + +- [ ] 6.1 Implement CI workflow for changed-package detection, versioning, build/type/test checks, and publish. +- [ ] 6.2 Implement dependency-safe multi-package publish ordering. +- [ ] 6.3 Add dry-run and consumer smoke-install validation before publish steps. +- [ ] 6.4 Add compatibility gates for SemVer policy and npm channel/tag correctness. +- [ ] 6.5 Add Convex compatibility validation (minimum/current supported contract matrix) in release checks. + +## 7. Documentation And Validation + +- [ ] 7.1 Update package installation docs and release runbook to match final portfolio distribution paths. +- [ ] 7.2 Publish package matrix documentation (scope, support tier, channels, and support windows). +- [ ] 7.3 Document Convex compatibility/versioning guidance and migration workflows. +- [ ] 7.4 Validate installation in clean consumer fixtures for each package type in the first cohort. diff --git a/openspec/changes/rank-intercom-alternative-intent-cluster/.openspec.yaml b/openspec/changes/seo-launch-intercom-authority-distribution/.openspec.yaml similarity index 100% rename from openspec/changes/rank-intercom-alternative-intent-cluster/.openspec.yaml rename to openspec/changes/seo-launch-intercom-authority-distribution/.openspec.yaml diff --git a/openspec/changes/launch-intercom-authority-distribution/design.md b/openspec/changes/seo-launch-intercom-authority-distribution/design.md similarity index 100% rename from openspec/changes/launch-intercom-authority-distribution/design.md rename to openspec/changes/seo-launch-intercom-authority-distribution/design.md diff --git a/openspec/changes/launch-intercom-authority-distribution/proposal.md b/openspec/changes/seo-launch-intercom-authority-distribution/proposal.md similarity index 100% rename from openspec/changes/launch-intercom-authority-distribution/proposal.md rename to openspec/changes/seo-launch-intercom-authority-distribution/proposal.md diff --git a/openspec/changes/launch-intercom-authority-distribution/specs/mentions-proof-surface/spec.md b/openspec/changes/seo-launch-intercom-authority-distribution/specs/mentions-proof-surface/spec.md similarity index 100% rename from openspec/changes/launch-intercom-authority-distribution/specs/mentions-proof-surface/spec.md rename to openspec/changes/seo-launch-intercom-authority-distribution/specs/mentions-proof-surface/spec.md diff --git a/openspec/changes/launch-intercom-authority-distribution/specs/seo-authority-tracking-and-refresh-cycle/spec.md b/openspec/changes/seo-launch-intercom-authority-distribution/specs/seo-authority-tracking-and-refresh-cycle/spec.md similarity index 100% rename from openspec/changes/launch-intercom-authority-distribution/specs/seo-authority-tracking-and-refresh-cycle/spec.md rename to openspec/changes/seo-launch-intercom-authority-distribution/specs/seo-authority-tracking-and-refresh-cycle/spec.md diff --git a/openspec/changes/launch-intercom-authority-distribution/specs/seo-distribution-playbook-and-asset-pack/spec.md b/openspec/changes/seo-launch-intercom-authority-distribution/specs/seo-distribution-playbook-and-asset-pack/spec.md similarity index 100% rename from openspec/changes/launch-intercom-authority-distribution/specs/seo-distribution-playbook-and-asset-pack/spec.md rename to openspec/changes/seo-launch-intercom-authority-distribution/specs/seo-distribution-playbook-and-asset-pack/spec.md diff --git a/openspec/changes/launch-intercom-authority-distribution/tasks.md b/openspec/changes/seo-launch-intercom-authority-distribution/tasks.md similarity index 100% rename from openspec/changes/launch-intercom-authority-distribution/tasks.md rename to openspec/changes/seo-launch-intercom-authority-distribution/tasks.md diff --git a/openspec/changes/seo-rank-intercom-alternative-intent-cluster/.openspec.yaml b/openspec/changes/seo-rank-intercom-alternative-intent-cluster/.openspec.yaml new file mode 100644 index 0000000..5aae5cf --- /dev/null +++ b/openspec/changes/seo-rank-intercom-alternative-intent-cluster/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-04 diff --git a/openspec/changes/rank-intercom-alternative-intent-cluster/design.md b/openspec/changes/seo-rank-intercom-alternative-intent-cluster/design.md similarity index 100% rename from openspec/changes/rank-intercom-alternative-intent-cluster/design.md rename to openspec/changes/seo-rank-intercom-alternative-intent-cluster/design.md diff --git a/openspec/changes/rank-intercom-alternative-intent-cluster/proposal.md b/openspec/changes/seo-rank-intercom-alternative-intent-cluster/proposal.md similarity index 100% rename from openspec/changes/rank-intercom-alternative-intent-cluster/proposal.md rename to openspec/changes/seo-rank-intercom-alternative-intent-cluster/proposal.md diff --git a/openspec/changes/rank-intercom-alternative-intent-cluster/specs/intercom-alternative-intent-pages/spec.md b/openspec/changes/seo-rank-intercom-alternative-intent-cluster/specs/intercom-alternative-intent-pages/spec.md similarity index 100% rename from openspec/changes/rank-intercom-alternative-intent-cluster/specs/intercom-alternative-intent-pages/spec.md rename to openspec/changes/seo-rank-intercom-alternative-intent-cluster/specs/intercom-alternative-intent-pages/spec.md diff --git a/openspec/changes/rank-intercom-alternative-intent-cluster/specs/intercom-comparison-and-migration-pages/spec.md b/openspec/changes/seo-rank-intercom-alternative-intent-cluster/specs/intercom-comparison-and-migration-pages/spec.md similarity index 100% rename from openspec/changes/rank-intercom-alternative-intent-cluster/specs/intercom-comparison-and-migration-pages/spec.md rename to openspec/changes/seo-rank-intercom-alternative-intent-cluster/specs/intercom-comparison-and-migration-pages/spec.md diff --git a/openspec/changes/rank-intercom-alternative-intent-cluster/specs/landing-seo-cluster-linking-and-schema/spec.md b/openspec/changes/seo-rank-intercom-alternative-intent-cluster/specs/landing-seo-cluster-linking-and-schema/spec.md similarity index 100% rename from openspec/changes/rank-intercom-alternative-intent-cluster/specs/landing-seo-cluster-linking-and-schema/spec.md rename to openspec/changes/seo-rank-intercom-alternative-intent-cluster/specs/landing-seo-cluster-linking-and-schema/spec.md diff --git a/openspec/changes/rank-intercom-alternative-intent-cluster/tasks.md b/openspec/changes/seo-rank-intercom-alternative-intent-cluster/tasks.md similarity index 100% rename from openspec/changes/rank-intercom-alternative-intent-cluster/tasks.md rename to openspec/changes/seo-rank-intercom-alternative-intent-cluster/tasks.md diff --git a/openspec/specs/ai-handoff-response-traceability/spec.md b/openspec/specs/ai-handoff-response-traceability/spec.md new file mode 100644 index 0000000..ebe264e --- /dev/null +++ b/openspec/specs/ai-handoff-response-traceability/spec.md @@ -0,0 +1,35 @@ +# ai-handoff-response-traceability Specification + +## Purpose +TBD - created by archiving change persist-full-ai-response-on-handoff. Update Purpose after archive. +## Requirements +### Requirement: Handoff outcomes MUST retain full generated AI response context for review + +When a handoff occurs after AI generation, review records SHALL retain generated response content and associated source/confidence metadata. + +#### Scenario: Handoff triggered after AI generates candidate response + +- **WHEN** AI produces a candidate response and handoff decision is triggered +- **THEN** AI review records SHALL persist generated candidate response context +- **AND** handoff reason metadata SHALL remain attached + +### Requirement: Visitor-facing thread MUST continue showing handoff message only + +Handoff traceability changes MUST NOT alter visitor-facing behavior that displays a single handoff message in the conversation thread. + +#### Scenario: Visitor receives handoff reply + +- **WHEN** handoff path is executed +- **THEN** conversation thread SHALL show the configured handoff message +- **AND** unsent generated candidate response SHALL not be posted to visitor thread + +### Requirement: AI review payloads MUST distinguish generated and delivered response contexts + +AI review query responses SHALL indicate whether displayed text is generated candidate content or delivered handoff content for handed-off records. + +#### Scenario: Operator opens AI review for handed-off conversation + +- **WHEN** AI review is opened for a handed-off interaction +- **THEN** the UI payload SHALL provide both generated candidate and delivered handoff contexts when available +- **AND** labels SHALL allow operator to distinguish the two +