moreminimore-chat/HANDOFF.md

# HANDOFF

## ═══════ SESSION 2026-08-22 — Final decision: external n8n (Option 3) ═══════

- User selected Option 3: n8n remains a separate service for the LLM chatbot/workflow path.
- Do not integrate Hermes, embed n8n, or change Chatwoot production code for this decision.
- Keep the existing AgentBot async webhook boundary: Chatwoot → external n8n → configured LLM/external services → Chatwoot API reply.
- The Gateway/Adapter design is deferred; implement it only if later requirements justify centralized tenant isolation, idempotency, DLQ, observability, or provider routing.
- Only this handoff/log decision is updated; production source remains unchanged.

## ═══════ SESSION 2026-08-22 — LLM chatbot runtime architecture discovery ═══════

- Read-only architecture review for `/Users/kunthawat/Gitea/Chatwoot`; no production code changed.
- Chatwoot's existing AgentBot path is already the intended boundary: async signed webhook out, external runtime processes, then external runtime posts an outgoing message through Chatwoot API. `outgoing_url` is not an LLM request/response endpoint.
- Hermes is technically feasible only behind a bridge. Hermes API server is the preferred execution interface; Hermes webhook adapter is not plug-compatible because signature headers and response delivery contract differ.
- Recommended target: `Chatwoot AgentBot → dedicated Hermes bridge → Hermes API → Chatwoot API`; optional external n8n remains for visual workflows, CRM/LINE/ERP side effects, and integrations. Do not embed n8n or give a customer-facing Hermes profile unrestricted terminal/file tools.
- Tenant rules: keep Chatwoot as transcript/source of truth; namespace every request by account/inbox/conversation; do not treat Hermes personal memory/profile files as a multi-tenant knowledge base. Use allow-listed tools, sandboxing, idempotency, HMAC verification, secret rotation, and human handoff.
- Next implementation gate: P0 one-account bridge proof (or n8n→Hermes proof), message-created only, no loop, signed webhook verification, reply via bot token, duplicate/retry tests, cross-tenant isolation test, and latency/error telemetry.
- Working tree was already dirty with unrelated M1/M2 changes; future bridge work must use a separate worktree/branch.


## ═══════ SESSION 2026-08-19 — Moreminimore Chat: rebrand + M1 + M2 work ═══════

## Current state (2026-08-19)
Repo `/Users/kunthawat/Gitea/Chatwoot`, branch `develop`, **pushed to Gitea**.
Remote origin = `ssh://git@moreminimoreapps-gitea.ahkhwd.easypanel.host:2222/kunthawat/moreminimore-chat` (NOT github).
SSH push via port **2222** (the HTTPS path git.moreminimore.com gets nginx 413; SSH port 22 is not Gitea SSH).
HEAD = `ccff2dfca`. Worktree clean except untracked `.hermes/plans/` (never commit).

### Completed this session (all through independent five-key reviews, deployed by user)
- **Rebrand → Moreminimore Chat** complete (phases 1-3 + Dockerfile + brand DB fix): f17ce89, d925ab1, 18e6fc28a, bee28c32e, d77d60443, 4b35130ae.
- **Docker/build**: root `Dockerfile` added (4b35130ae) so EasyPanel 'Dockerfile' builder works instead of Nixpacks rbenv stack. nixpacks.toml added then removed (wrong approach).
- **M1 — per-account OpenAI custom base URL** (the /app/accounts/{id}/settings/integrations/openai page): commit f9628db0e. Adds optional custom OpenAI-compatible base_url per account (apps.yml schema+form, llm_base_service api_base priority hook.base_url→CAPTAIN_OPEN_AI_ENDPOINT→api.openai.com, key_validator base_url kwarg, hook https validation). NOTE: an earlier wrong-scope Captain-level provider switch (46fe70398) was reverted (961ecd388) — the Captain CAPTAIN_OPEN_AI_ENDPOINT already supports custom URL as original behavior, so no change needed there.
- **M2 — analytics foundation** (self-improving chatbot, admin-only):
  - 9fbb0da9b `conversation_daily_metrics` (per account/day; tags, deal outcomes, peak hours, agent/team/channel/inbox breakdown)
  - 0fad9ce6b `customer_daily_metrics` (per customer/day; agent_ids)
  - 161e4210b `product_catalog_entries` (per-account hierarchical product reference: group>subgroup>product+aliases)
  - ccff2dfca `lib/llm/resolver.rb` (LLM cascade: per-account openai hook → Captain → nil; https-only api_base)
- **DB brand fix** done by user on prod (login no longer shows Chatwoot / logo loads).

### M2 design decisions (approved by user — IMPORTANT for remaining work)
- Analyze EVERY chat of EVERY account daily (high LLM cost accepted — selling point is self-improving chatbot).
- LLM cascade: per-account openai → fallback Captain config → if neither, feature disabled (LLM integration effectively always on unless Captain unset).
- Use Chatwoot's ORIGINAL conversation tags (ActsAsTaggableOn tag_list) — do NOT add many tag fields. Product/sale tag goes into the same tag list, prefixed (e.g. lines like `group>subgroup>product` joined, or `สินค้า:...`/`กลุ่ม:...`). Daily metric `top_tags` aggregates from these.
- **No `tagged_at`** (user decided to skip time-tracking to avoid DB complexity).
- Per-day stats are IMMUTABLE snapshots; conversation live tags get re-tagged on later analysis (e.g. session now about product B → product A tag removed). The daily snapshot preserves the earlier state.
- Report page **admin-role ONLY** (agent must NOT see deep analytics). Filter by agent/team/inbox/channel/tag/sale-tag/time + cross-analysis. Break down per CUSTOMER and per AGENT.
- Weekly (Mon 10:00) LLM summarizes 7 days → persona improvement recommendation (summary only, NOT full prompt). Delivered via preferred channel: Line (has quick-replies) / Telegram (inline keyboard) / webhook (3rd party). Admin chooses approve / view-full-prompt / reject; viewing full prompt → re-approve; on approve → webhook with prompt (admin sets URL+secret).
- Product list: per-account, admin-only menu (like report), import via copy/paste or CSV/XLSX. Multi-level hierarchy (big group>subgroup>product>display) — LLM matches from lowest level first, tags ancestors; supports multiple products/groups per chat.

### NEXT TO DO (M2 remaining — biggest remaining work)
1. **part2b-ii — LLM classifier service: ✅ DONE (2026-08-19)**. New `lib/llm/analytics_classifier.rb` — reads conversation, classifies via `Llm::Resolver` cascade + `with_schema` JSON output → `Result` (topics, products via tag_hierarchy path mapping, deal won/lost/undecided). Fail-closed on no-credential (returns `disabled`, never calls LLM / sends content). Also fixed: `Account` missing `has_many :product_catalog_entries` (foundation `161e4210b` wired model+migration but not the reverse association → would NoMethodError). Verified: `ruby -c` clean (2.6/3.4), isolated smoke 8/8 under Ruby 3.4.10 (found `/opt/homebrew/opt/ruby@3.4/bin/ruby` — real 3.4.10 available, `.ruby-version`=3.4.4), static scan clean, independent reviewer `deleg_47c1a2cb` = complete 5-key PASS (non-blocking em-dash escape fix applied). Plan doc: `.hermes/plans/2026-08-19-m2-self-improving-analytics.md`.
2. **part2b-iii — daily batch job: ✅ DONE (2026-08-19)**. New `app/services/analytics/account_daily_processor.rb` (per-account/date: UTC day window from `account.reporting_timezone`, selects active conversations, classifies via `Llm::AnalyticsClassifier` fail-closed, re-tags replacing M2-managed tags + preserving manual labels, upserts ConversationDailyMetric unique account+date + CustomerDailyMetric unique account+contact+date) + `app/jobs/analytics/daily_metrics_job.rb` (per-account rescue, yesterday in account TZ) + `config/schedule.yml` entry `analytics_daily_metrics_job` `30 2 * * *` timezone `Asia/Bangkok`. Verified: `ruby -c` clean (3.4.10), smoke 15/15, static scan clean, schedule no dup keys, reviewer `deleg_fecf7c61` = complete 5-key PASS (4 non-blocking suggestions: add specs, N+1 in chat_message_count, deal_outcomes dual structure, apply_tags rescue scope).
3. **phase 2 — rollup + report: ✅ DONE (2026-08-19)**. Backend: `Analytics::ReportService` (summary/timeseries/customers/agents from immutable daily-metric tables; deal_outcomes normalization for 'totals'-nested + flat) + `Analytics::DrilldownService` (deep filterable drilldown over live conversations: since/until/agent/team/inbox/channel/tag/deal + pagination; fail-closed label-join) + `Api::V2::Accounts::AnalyticsReportsController` (admin-only via ReportPolicy#view?=administrator; summary + drilldown) + routes `analytics_reports` (get :summary/:drilldown). `AccountDailyProcessor#apply_tags` now writes `deal:<outcome>` tag for deal filtering. Frontend: `api/analyticsReports.js` + `AnalyticsReports.vue` (summary cards + filter bar + drilldown table) + route `analytics_reports` under reports section + `ANALYTICS_REPORTS` i18n keys in en/report.json. Verified: backend smoke 12/12, reviewers `deleg_6800b012` (backend) + `deleg_15f8447c` (frontend) = complete 5-key PASS (non-blocking i18n suggestions applied). NOTE: frontend full build (eslint/vite/vitest) cannot run locally (no node_modules) — run `pnpm install && pnpm test` before ship.
4. **phase 3 — import + persona eval + approval (2026-08-20):**
   - **Weekly persona eval** ✅: `Analytics::WeeklyPersonaEvaluator` (7d via ReportService → LLM summary+recommendations; summary-only, no PII) + `persona_evaluation` endpoint + route. Reviewer `deleg_b7d63fd7` PASS.
   - **Frontend product-catalog import UI** ✅: `api/productCatalog.js` + `productCatalog/Index.vue` (paste + xlsx/csv upload + result + table) + admin-only route. Reviewer `deleg_0e9f9291` PASS (i18n suggestions applied).
   - **Approval flow** (user chose **LINE primary + webhook fallback**, then added **Telegram**; precedence LINE → Telegram → webhook): `Analytics::PersonaApprovalService` (`deliver` LINE quick-reply / Telegram inline keyboard / webhook fallback; `notify_approval` webhook-only w/ decision) + `Analytics::WeeklyPersonaEvaluationJob` + controller (`persona_evaluation_deliver`, `persona_approval_settings` [line_user_id + telegram_chat_id + webhook_url, conditional], `persona_decision`) + routes + schedule.yml `analytics_weekly_persona_evaluation_job` (Mon 10:00 Asia/Bangkok). First reviewer `deleg_1fe19871` FAIL-CLOSED (1 medium logic error: `:approve` path LINE-first + decision not passed) → **FIXED** (webhook-only `notify_approval(decision)`) → re-review `deleg_3052f7a4` PASS; Telegram `deleg_34116d1a` PASS. Config: `persona_line_user_id` / `persona_telegram_chat_id` / `persona_webhook_url` / `persona_webhook_secret` in Account#custom_attributes.
   - **Docs** — via HANDOFF.md/plan doc; no separate docs/ convention.
   - **POST-MVP design note (prompt webhook handshake) — user clarified, NOT built, awaiting LLM-server details**: a SEPARATE LLM server holds/applies the actual prompt; this app connects via webhook — (1) connect-first: pull current prompt (GET) + store snapshot; (2) approve weekly recommendation → POST new prompt to LLM server to apply. Analytics here ONLY surfaces "what customers asked" + recommendations; knowledge-prep/prompt-authoring is admin/LLM-server side. Delivery-webhook design (REST 2-endpoint vs generic action-body) DEFERRED — user wants document/design only for now.
   Verified: smoke tests (eval 8/8, import 10/10 + xlsx 5/5, approval 10/10 incl. Telegram), `ruby -c` clean, node --check on .js, schedule.yml valid + unique keys, static scan clean across all.

### Verification notes / blockers
- Ruby env active is 2.6.10; target 3.4.4. Rails/RSpec/RuboCop cannot be reliably claimed passed. Ruby `ruby -c` syntax + YAML validity + isolated smoke tests used instead.
- Full Vitest baseline is clean under TZ=UTC: 414 files / 4176 tests, 0 failed.
- Enterprise (EE) files still read CAPTAIN_OPEN_AI_ENDPOINT directly and won't honor per-account base_url gating — intentional (out of OSS scope), note as follow-up.
- No secrets committed. Temporary test helpers under /tmp only.

## ───────── historical (2026-08-16, before this session) ─────────


### Latest handoff — 2026-08-16 (updated after rebrand + push)
- Rebrand to **Moreminimore Chat** complete across all phases (committed): `f17ce89` (phase 1 configurable brand core: logo/config/mailer defaults/views), `d925ab1` (phase 2a cleanup + 512px thumbnail), `18e6fc28a` (phase 2b color theme: black #333333 primary + Moreminimore yellow #FED400 accent), `bee28c32e` (phase 3 visible surfaces: app.json + mailers + 56 locales + prompts). All phases passed independent five-key reviews (deleg_a733cdf4, deleg_37455fbd, deleg_9b054593, deleg_892d115f).
- **PUSHED to Gitea** via SSH port 2222: branch `develop` (HEAD `bee28c32e`) now on `kunthawat/moreminimore-chat`. Remote `origin` = `ssh://git@moreminimoreapps-gitea.ahkhwd.easypanel.host:2222/kunthawat/moreminimore-chat`. HTTPS push to `git.moreminimore.com` is blocked by nginx 413 (client_max_body_size < ~237MB pack); SSH port 22 is NOT Gitea SSH — use 2222. `upstream` (github.com/chatwoot) removed; Gitea rejects shallow push, so unshallow first. SSH key `moreminimore-local-ed25519` added via Gitea API.
- Earlier checkpoints: `19dc449` SM-07, `2ef6fa5` SM-07 remediation (approved deleg_087e4a3f), `364e72f` SM-08, `8101395` residual Hub removal (approved deleg_49d6ee2e + deleg_58a576e1).

### Verified checkpoints
- `8ebb320` — privacy/branding audit harness.
- `832a7fd` — Hub sync/registration/telemetry removal.
- `1a3697f` — restored only the compatibility APIs required by direct push/billing callers.
- `8b1a033` — removed the Chatwoot Hub push relay; exact post-commit independent review passed.
- `3458272` — removed cwctl telemetry from the installer; exact post-commit independent review passed.
- `d9bf4c4` — removed community signup/onboarding website-branding enrichment; split exact post-commit reviews `deleg_5e2578c5` (backend) and `deleg_ee3e217f` (frontend) passed with empty blocking arrays.
- `ced77af` — SM-06 Product Analytics removal and dashboard config allowlist remediation; pre-commit review `deleg_f9644984` and exact post-commit review `deleg_9b0a2f63` passed with empty security/logic arrays.

### Current work / uncheckpointed work
- SM-05 community signup enrichment removal is checkpointed at `d9bf4c4`; pre-commit review, commit hooks, and split exact post-commit reviews passed. The enterprise service/spec remain unchanged and fail with `NameError: uninitialized constant WebsiteBrandingService`. This remains an explicit architecture/legal blocker; do not add a dummy service or restore remote enrichment.
- SM-06 is verified at `ced77af`. Its follow-up fix applies `.slice(*GLOBAL_CONFIG_KEYS)` before merging `app_config`, preventing stale/unrequested values such as `CLOUD_ANALYTICS_TOKEN` from reaching serialized `window.globalConfig`. SM-07 local-only observability and the remaining SM-08 dashboard/config script-injection work are still uncheckpointed. The community Help Center SM-08 correction is committed as `5619cc3`: remove GTM remote-container execution, reject/remove legacy GTM config, and retain only fixed allow-listed provider snippets for explicit admin configuration. Exact post-commit review `deleg_dd3db5b7` passed with empty blocking arrays. Enterprise marketing conversion tracking remains outside this community scope pending legal/compatibility review.

### Evidence and blockers
- SM-03 exact post-commit review passed for `1a3697f..8b1a033`; reviewer suggestions are to add explicit missing/blank/partial Firebase negative coverage and clarify legacy FCM configuration names in `.env.example`.
- SM-04 exact post-commit review passed for `1a3697f..3458272`; Bash 3.2 compatibility and fail-closed privacy-test behavior were verified.
- SM-05 exact committed range `3458272..d9bf4c4` passed split independent reviews: backend `deleg_5e2578c5` and frontend `deleg_ee3e217f`; both returned complete five-key verdicts with empty security and logic arrays. Frontend targeted run passed 9 suites/8 tests. Backend RSpec rerun is environment-blocked because Ruby 3.4.4 is required but only 3.4.10 is installed and the bundle has no usable `rspec` executable.
- SM-06 exact committed range `a96b977..ced77af` changed one controller line and passed fresh pre-commit/post-commit independent review. Raw merge leaked a stubbed analytics token; the allowlist slice now removes unrequested keys before layout serialization. Committed Ruby syntax, diff check, and security scan passed. Rails RSpec/RuboCop remain blocked because the active Ruby is 2.6.10 and Bundler 2.5.16 is unavailable.
- SM-08 exact post-commit review `deleg_dd3db5b7` passed for `d9bf4c4..5619cc3`; 57 portal model/controller examples, GTM regression 3/3, Ruby/ERB syntax, RuboCop, ESLint/Prettier, Vite build and privacy-audit harness passed. Full Vitest with `TZ=UTC` passes 414 files / 4176 tests, 0 failed.
- No push or deploy has occurred.
- Approved product name, domains, logos/icons and sender/legal values are still missing; stop before SM-09/10.
- Full Rails/frontend suites, production-like DB checks, HTTP/DNS egress capture, `git fetch --unshallow`, and upstream merge rehearsal remain outstanding. The full Vitest frontend baseline is clean under `TZ=UTC`: 414 files / 4176 tests passed, 0 failed (the earlier "407/15 failed" record was a non-UTC run artifact; timezone-sensitive tests all pass under UTC).
- Temporary test services/configuration stay under `/tmp`; never commit them or secrets.

### Repository baseline
- Path: `/Users/kunthawat/Gitea/Chatwoot`
- Origin: `https://github.com/chatwoot/chatwoot.git`
- Branch: `develop`
- Initial baseline commit: `9a73c1473ffa0ae6a9c7725046b8ca17922dcc83`
- Latest checkpoint: `ced77af` (SM-06 Product Analytics plus dashboard config allowlist remediation; exact post-commit review `deleg_9b0a2f63` passed). SM-08 Help Center remains separately verified at `5619cc3`.
- Clone is shallow; fetch full upstream history before merge/rebase rehearsal.

### Primary deliverable
- `.hermes/plans/2026-08-15_092534-chatwoot-private-rebrand.md`
- Small-model execution index: `.hermes/plans/chatwoot-private/README.md`
- The execution package contains `00-execution-contract.md` plus runbooks `01`–`12` with 58 unique `SM-*` tasks. Send only one task at a time and review its exact diff/test evidence before advancing.

### Most important finding
`DISABLE_TELEMETRY=true` is not a complete opt-out. `lib/chatwoot_hub.rb` still posts `instance_config` to the Hub; it only omits `instance_metrics`. The corresponding behavior is asserted in `spec/lib/chatwoot_hub_spec.rb`.

### Other unsolicited/vendor-controlled egress to remove
- Chatwoot Hub daily sync and onboarding registration
- Chatwoot Hub `/send_push` relay fallback
- Hub-hosted changelog fetch
- silent cwctl command reporting to the Hub
- automatic signup email-domain website/DNS branding enrichment
- Amplitude browser analytics
- Sentry/frontend/backend remote error reporting
- optional remote APM agents
- arbitrary dashboard scripts and remote GTM container execution
- enterprise marketing conversion tracking (proprietary/cloud-only; pending separate legal/compatibility decision)

### Implementation order
1. Follow dependency order in `.hermes/plans/chatwoot-private/README.md`.
2. Establish the baseline and privacy audit harness before behavior changes.
3. Remove Hub sync/registration/manual refresh, push relay, cwctl telemetry, signup-domain enrichment and remote changelog.
4. Neutralize/remove analytics, remote error reporting/APM and script injection.
5. Stop at the Runbook 09 input gate until approved brand values/assets are supplied.
6. Add central brand defaults and replace visible assets/copy without renaming compatibility APIs.
7. Run static and isolated dynamic egress gates, positive feature-traffic tests, full review and visual QA.
8. Complete upstream-history and merge-rehearsal workflow; never mix upstream merge with customization commits.

### User decisions required before implementation
- Product name, canonical/support/docs domains, logos/icons and email sender name
- Private Gitea repository name
- Whether to keep deprecated widget API aliases (recommended: yes)
- Whether local-only logs are sufficient or a self-hosted observability endpoint is required
- Push notification plan and own FCM/VAPID credentials

### Safety/legal notes
- Root is MIT, but `enterprise/` is proprietary; do not ship enterprise features without a separate license.
- No remote repository was created, no files were pushed and no deployment was performed.