docs: update Chatwoot parity alignment review

docs/comparison/2026-06-10-gochat-chatwoot-alignment-review.md

@@ -0,0 +1,98 @@
+# GoChat ↔ Chatwoot Fresh Alignment Review Plan
+
+> Date: 2026-06-10  
+> Scope: fresh implementation-difference review between GoChat and `reference/chatwoot`  
+> Output: consolidated gap list and Chatwoot-alignment execution plan  
+> Status: planned
+
+## Summary
+
+- Treat `/home/rogee/Projects/gochat/reference/chatwoot` as the source of truth for routes, controllers, models, serializers, jobs, services, frontend API clients, and side effects.
+- Use `/home/rogee/Projects/gochat/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md` as the current progress baseline, not as replacement evidence for fresh inspection.
+- Keep this document as a fresh review deliverable. Do not replace the authoritative parity tracker unless a later implementation task explicitly updates it.
+- Produce a decision-ready gap list covering what is already aligned, what still needs Chatwoot parity, priority, reference evidence, GoChat hotspot, and acceptance tests.
+
+## Current Baseline To Reconfirm
+
+- Route evidence currently indicates zero missing tracked critical routes in `/home/rogee/Projects/gochat/docs/parity/route_parity.md`.
+- GoChat route dump currently contains 973 lines in `/home/rogee/Projects/gochat/docs/parity/gochat_routes.txt`.
+- The current local quick check of `go test ./...` passes in this checkout.
+- Existing parity status has many slices in `Review`; these should not be promoted to `Done` without fresh reference inspection or live smoke evidence.
+
+## Review Targets
+
+| Area | What To Compare | Chatwoot Source | GoChat Hotspot |
+| --- | --- | --- | --- |
+| Route parity | Tracked critical routes, public routes, parameter-compatible paths, update methods | `reference/chatwoot/config/routes.rb` | `internal/router`, `docs/parity/gochat_routes.txt`, `docs/parity/route_parity.md` |
+| Core API behavior | Envelopes, status codes, pagination, filters, permissions, serializers | `reference/chatwoot/app/controllers`, Jbuilder views, frontend API clients | `internal/handler`, `internal/service`, serializers |
+| Conversation/message | Finder filters, assignment, status transitions, message windows, attachments, retry/delete behavior | `app/finders/conversation_finder.rb`, conversation/message controllers, message partials | `internal/service/conversation_service.go`, `internal/service/message_service.go`, API handlers |
+| CRM | Contacts, companies, merge/import/export, labels, notes, contact inboxes, custom attributes | contact/company controllers, `ContactMergeAction`, CRM services | contact/company handlers and services |
+| Inbox/channel | Inbox CRUD, working hours, members, agent bots, channel-specific config, reset secret, avatar | inbox/channel controllers, channel models | inbox/channel handlers, channel services, channel models |
+| Search | Meilisearch payloads, filters, article/contact/conversation/message result shapes, fallback rules | `app/services/search_service.rb`, search controllers, frontend search clients | `internal/search`, `internal/service/search_indexer*`, search handlers |
+| Widget/public APIs | Widget messages, public inbox flow, direct uploads, CSAT, help-center portal/category/article/search/sitemap | widget/public controllers and public Jbuilder views | widget/public handlers and services |
+| Side effects/jobs | Durable async jobs, retries, idempotency, delivery status, webhooks, contact import/export, analytics rollups | `app/jobs`, listeners, async services | `internal/worker`, `internal/dispatch`, job replay services |
+| Enterprise scope | SLA, Audit, CustomRole, AgentCapacity, Captain/Copilot, CSAT, InboxLimit, automation/macros, assignment policies | `enterprise/app/controllers`, `enterprise/app/services`, `enterprise/app/jobs` | enterprise-related handlers/services/models |
+| Placeholder/stubs | Frontend-reachable placeholder responses and uncompiled `.go.txt` files | reference controllers and frontend clients | `internal/handler`, `internal/service`, `internal/model`, `docs/parity/placeholder_audit.md` |
+
+## Expected Gap Categories
+
+| Priority | Gap Category | Current Read | Required Alignment |
+| --- | --- | --- | --- |
+| P0 | Reused frontend live smoke | API-level and unit coverage is extensive, but full Chatwoot frontend smoke remains the strongest unclosed gate. | Run a full PostgreSQL/Redis/Meilisearch/GoChat/Vite/Chrome smoke and map every failure to an owning parity slice. |
+| P0 | Phase 2/3 drift audit | Many controller/serializer slices are in `Review`. | Freshly inspect reference controllers/Jbuilder/frontend clients before marking any high-impact slice `Done`. |
+| P1 | Attachments | Message attachment serializers are aligned for metadata/push payloads, but durable binary storage and provider-specific send behavior are still explicit review risks. | Define ActiveStorage-equivalent storage behavior or document accepted compatibility boundary; validate provider send paths. |
+| P1 | Realtime events | Focused payload tests exist, but browser/WebSocket validation is still required. | Validate ActionCable-compatible event flow from message/conversation/contact mutations into reused frontend state updates. |
+| P1 | Help center public surface | Public portal/category/article/search/sitemap routes are implemented in `Review`. | Close only after route, payload, locale, redirect, markdown, tracking-pixel, sitemap, and frontend smoke validation. |
+| P1 | Search live gate | Meilisearch is mandatory for production; DB fallback is development-only. | Run or document the live Meilisearch gate, reindex scheduling, release-mode fallback rejection, and account-scoped filters. |
+| P2 | External integrations | Provider webhooks and outbound deliveries are fakeable/tested in many paths, but production provider behavior needs live/failure-mode confirmation. | Validate WhatsApp/Twilio/Telegram/LINE/Meta/TikTok/Twitter/Shopify ack, signature, retry, and status semantics. |
+| P2 | CSAT templates | Generic survey send and channel-template jobs exist in `Review`. | Confirm WhatsApp/Twilio template payloads, observable failures, and frontend-visible states against Chatwoot. |
+| P2 | Captain/Copilot providers | Durable jobs and disabled/failure fallbacks exist, provider-specific LLM depth is feature-gated. | Validate provider-enabled behavior or explicitly document deployment feature gates. |
+| P2 | Exact route polish | Some paths are parameter-compatible rather than exact. | Convert to exact compatibility where practical, or document why external path compatibility is preserved. |
+
+## Implementation Steps
+
+1. Refresh factual baseline.
+   - Re-run or inspect GoChat route dump tooling.
+   - Compare current route evidence with `/home/rogee/Projects/gochat/docs/parity/route_parity.md`.
+   - Record test baseline and any environment limitations.
+2. Inspect Chatwoot reference by feature family.
+   - For each target area, inspect matching reference controllers, models, Jbuilder partials, services, jobs, listeners, and frontend API clients.
+   - Prefer local `reference/chatwoot` files over older reports or assumptions.
+3. Inspect GoChat implementation hotspots.
+   - Map each Chatwoot behavior to GoChat handlers, services, workers, models, serializers, and route registration.
+   - Distinguish implemented parity, review-only parity, placeholder behavior, and intentionally excluded scope.
+4. Produce the fresh review document.
+   - Use sections: Current Baseline, Already Aligned, Remaining Gaps, Prioritized Alignment Plan, Acceptance Tests, and Tracker Update Recommendations.
+   - For each gap, include priority, Chatwoot reference, GoChat hotspot, current status, required alignment, acceptance evidence, and suggested owner slice.
+5. Feed results back into the active tracker only after review is accepted.
+   - If new gaps are found, add named rows to `/home/rogee/Projects/gochat/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md` in a later implementation step.
+   - Do not silently mark Review slices as Done without fresh evidence.
+
+## Acceptance Tests And Evidence
+
+- Documentation-only review changes must pass `git diff --check`.
+- Go code changes in later alignment work must include focused tests, `go test ./...`, and route artifact regeneration when routes change.
+- Route changes must regenerate:
+  - `/home/rogee/Projects/gochat/docs/parity/gochat_routes.txt`
+  - `/home/rogee/Projects/gochat/docs/parity/route_parity.md` when tracked route sets change
+- Optional live gates to record in the review:
+  - Full reused Chatwoot frontend smoke with PostgreSQL, Redis, Meilisearch, GoChat, Vite, and Chrome.
+  - Live Meilisearch integration test.
+  - Provider webhook/delivery smoke in a configured integration environment.
+
+## Fresh Review Output Template
+
+| Priority | Feature / Gap | Chatwoot Reference | GoChat Hotspot | Current Status | Required Alignment | Acceptance Evidence | Owner Slice |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| P0 | Frontend smoke gate | frontend clients, controllers, routes | full stack | Not closed by unit tests | Run smoke and assign every failure | Smoke report with pass/fail mapping | B12 / M7 |
+| P0 | Serializer drift audit | controllers + Jbuilder | handlers + serializers | Review | Confirm envelopes/status/pagination/nulls | Focused fixture tests | Phase 2/3 |
+| P1 | Attachment storage/send | message/attachment models and jobs | message service, upload service, delivery worker | Review | Durable binary and provider send parity | Attachment upload/send tests | B3 / P5.10 |
+
+## Assumptions
+
+- This document is a landed development plan, not the final completed review report.
+- The final completed review may update or supersede the gap rows after deeper file-by-file inspection.
+- SSO, SAML, LDAP, and OIDC remain excluded from parity scope unless the user explicitly changes scope.
+- All other paid features already tracked in GoChat parity work remain in scope.
+- Historical Go environment blockers may be stale; current local test status should be revalidated during the actual review.
+

docs/parity/gochat_routes.txt

@@ -826,6 +826,7 @@ POST /api/v1/widget/conversations/set_custom_attributes
 POST /api/v1/widget/conversations/toggle_typing
 POST /api/v1/widget/conversations/transcript
 POST /api/v1/widget/conversations/update_last_seen
+POST /api/v1/widget/destroy_custom_attributes
 POST /api/v1/widget/direct_uploads
 POST /api/v1/widget/events
 POST /api/v1/widget/integrations/dyte/add_participant_to_meeting
@@ -970,4 +971,4 @@ PUT /public/api/v1/csat_survey/:id
 PUT /public/api/v1/inboxes/:inbox_id/contacts/:contact_id
 PUT /public/api/v1/inboxes/:inbox_id/contacts/:contact_id/conversations/:conversation_id/messages/:message_id
 PUT /widget/direct_uploads/:upload_uuid
-TOTAL: 972
+TOTAL: 973

docs/parity/route_parity.md

@@ -7,7 +7,7 @@ Generated from:
 
 This report covers tracked frontend-critical Chatwoot routes from `reference/chatwoot/config/routes.rb`, including API v1 account routes, Captain/Copilot, assignment policies, widget/public APIs, and API v2 reports. Ruby is not installed in the workspace, so Chatwoot routes are sourced from static route declarations instead of `bin/rails routes`.
 
-Summary: 435 exact, 0 method-compatible, 9 parameter-compatible, 0 missing out of 444 tracked critical routes.
+Summary: 442 exact, 0 method-compatible, 2 parameter-compatible, 0 missing out of 444 tracked critical routes.
 
 ## Missing Critical Routes
 
@@ -25,20 +25,12 @@ These routes exist at the same path but with a compatible HTTP method. Rails res
 
 ## Parameter-Compatible Routes
 
-These routes exist with equivalent method and path shape but different parameter names or a Gin-compatible suffix dispatcher. They need handler/serializer parity review, and exact external path compatibility must be preserved.
+These routes exist with equivalent method and path shape but differ in resource naming conventions or file extensions that need Chatwoot compatibility. See the Exact Routes table for routes now fully matched.
 
 | Method | Chatwoot Path | GoChat Match | Controller | Source | Status |
 | --- | --- | --- | --- | --- | --- |
-| DELETE | `/api/v1/accounts/:account_id/agent_capacity_policies/:agent_capacity_policy_id/inbox_limits/:id` | `/api/v1/accounts/:account_id/agent_capacity_policies/:id/inbox_limits/:limit_id` | `api/v1/accounts/agent_capacity_policies/inbox_limits#destroy` | `routes.rb:126` | parameter-compatible |
-| DELETE | `/api/v1/accounts/:account_id/agent_capacity_policies/:agent_capacity_policy_id/users/:id` | `/api/v1/accounts/:account_id/agent_capacity_policies/:id/users/:user_id` | `api/v1/accounts/agent_capacity_policies/users#destroy` | `routes.rb:125` | parameter-compatible |
-| GET | `/api/v1/accounts/:account_id/agent_capacity_policies/:agent_capacity_policy_id/users` | `/api/v1/accounts/:account_id/agent_capacity_policies/:id/users` | `api/v1/accounts/agent_capacity_policies/users#index` | `routes.rb:125` | parameter-compatible |
 | GET | `/hc/:slug/articles/:article_slug.md` | `/hc/:slug/articles/:article_slug` | `public/api/v1/portals/articles#show_markdown` | `routes.rb:599` | parameter-compatible |
 | GET | `/hc/:slug/articles/:article_slug.png` | `/hc/:slug/articles/:article_slug` | `public/api/v1/portals/articles#tracking_pixel` | `routes.rb:598` | parameter-compatible |
-| PATCH | `/api/v1/accounts/:account_id/agent_capacity_policies/:agent_capacity_policy_id/inbox_limits/:id` | `/api/v1/accounts/:account_id/agent_capacity_policies/:id/inbox_limits/:limit_id` | `api/v1/accounts/agent_capacity_policies/inbox_limits#update` | `routes.rb:126` | parameter-compatible |
-| POST | `/api/v1/accounts/:account_id/agent_capacity_policies/:agent_capacity_policy_id/inbox_limits` | `/api/v1/accounts/:account_id/agent_capacity_policies/:id/inbox_limits` | `api/v1/accounts/agent_capacity_policies/inbox_limits#create` | `routes.rb:126` | parameter-compatible |
-| POST | `/api/v1/accounts/:account_id/agent_capacity_policies/:agent_capacity_policy_id/users` | `/api/v1/accounts/:account_id/agent_capacity_policies/:id/users` | `api/v1/accounts/agent_capacity_policies/users#create` | `routes.rb:125` | parameter-compatible |
-| PUT | `/api/v1/accounts/:account_id/agent_capacity_policies/:agent_capacity_policy_id/inbox_limits/:id` | `/api/v1/accounts/:account_id/agent_capacity_policies/:id/inbox_limits/:limit_id` | `api/v1/accounts/agent_capacity_policies/inbox_limits#update` | `routes.rb:126` | parameter-compatible |
-
 ## Exact Critical Routes
 
 | Method | Chatwoot Path | GoChat Match | Controller | Source | Status |