docs: add issue 27 connections case study

Author: konard

docs/case-studies/issue-27/README.md

@@ -0,0 +1,126 @@
+# Issue 27 Case Study: DRY Connections UI
+
+Issue: https://github.com/link-foundation/meta-sovereign/issues/27
+
+Prepared on 2026-05-08 UTC for PR 28.
+
+## Summary
+
+Issue 27 follows up on issue 25. The core complaint was that data-heavy
+sections repeated the same provider setup UI inline, while the dedicated
+Connections section did not own the actual connection controls. That made
+the app feel noisy, duplicated, and harder to learn.
+
+The implemented solution makes Connections the single source of truth for
+provider setup. Data sections now keep their empty-state explanation and a
+small button that deep-links to the relevant provider detail. Each provider
+detail now contains instructions, credential fields, archive import, and the
+direct probe action.
+
+## Local Artifacts
+
+Raw GitHub data is preserved under `data/`:
+
+- `issue-27.json` and `issue-27-comments.json`
+- `issue-25.json` and `issue-25-comments.json`
+- `pr-28.json`, `pr-28-conversation-comments.json`,
+  `pr-28-review-comments.json`, and `pr-28-reviews.json`
+- `pr-26-related.json`, `pr-26-conversation-comments.json`,
+  `pr-26-review-comments.json`, and `pr-26-reviews.json`
+
+Final local verification logs are preserved under `verification-logs/`:
+
+- `local-npm-test-final.txt`
+- `local-npm-lint-final.txt`
+- `local-npm-format-check-after-logs.txt`
+- `local-jscpd-final.txt`
+- `local-build-web-final.txt`
+- `local-e2e-browser-run-final.txt`
+
+Referenced issue 25 screenshots are preserved under `screenshots/`:
+
+- `issue-25-desktop-current.png`
+- `issue-25-mobile-current.png`
+
+Final verification screenshot:
+
+- `final-connections-telegram-detail.png` shows the Telegram provider detail
+  owning setup instructions, credential fields, archive import, and the direct
+  probe button.
+
+The container did not include the `file` utility, so the downloads were
+validated with PNG magic bytes instead:
+
+```text
+89 50 4e 47 0d 0a 1a 0a
+```
+
+## Timeline
+
+- 2026-05-06 18:23 UTC: Issue 25 opened with the broader mobile-first,
+  translated, connection-centric UI vision.
+- 2026-05-06 18:23 UTC: PR 26 opened for issue 25.
+- 2026-05-06 20:08 UTC: PR 26 merged. It added the AppShell, Connections
+  module, provider list/detail instructions, and tutorial spotlight, but left
+  provider credential/import/probe controls in Settings and data-page guides.
+- 2026-05-08 10:52 UTC: Issue 27 opened to call out the remaining duplication.
+- 2026-05-08 10:53 UTC: Draft PR 28 opened for issue 27.
+
+## Observed Problem
+
+The issue 25 screenshots showed data-page empty states with full provider
+cards inline. Each card repeated archive instructions, API credential hints,
+docs links, and probe affordances. At the same time, Connections had a
+provider grid and instruction detail pages, but the operational controls
+still lived elsewhere. This created two mental models:
+
+- Data sections told users to "connect below" and exposed setup content inline.
+- Connections looked like the right destination, but did not contain the full
+  setup surface requested by the issue.
+
+## Root Causes
+
+1. `ConnectionGuide` was doing two jobs: empty-state education and provider
+   setup rendering. The guide was reused by many data surfaces, so every
+   provider card rendered repeatedly.
+2. `SettingsView` owned credential saving, archive import, and direct probes.
+   That ownership conflicted with the new issue 25 Connections module.
+3. The app's deep-link contract still targeted Settings anchors
+   (`#conn-{provider}`) instead of provider details inside Connections.
+4. Tests encoded the old Settings ownership path, so the issue 27 invariant
+   was not protected: data surfaces should link to Connections, not render
+   setup controls.
+
+## Implemented Fix
+
+- Replaced inline provider cards in `ConnectionGuide` with a compact
+  Connections CTA that dispatches `meta-sovereign:navigate` to the Connections
+  view and preserves `#conn-{provider}` anchors.
+- Moved credential forms, archive import, and direct probes into
+  `ConnectionDetail`.
+- Kept `SettingsView` as an app-level preferences page and added a clear
+  button to open Connections.
+- Updated Connections routing so direct hashes open the matching provider
+  detail and the Back action clears the provider hash.
+- Updated localized copy so data empty states point users to Connections while
+  keeping existing provider instructions and text in the app.
+- Added regression tests that fail if data guides render provider setup cards
+  or if provider details do not own credentials/import/probe controls.
+
+## External Project Issues
+
+No external upstream issue was filed. The problem was caused by local
+component responsibility and routing decisions, not by a third-party defect.
+
+## Verification Plan
+
+The PR should be accepted only when these checks pass. Local verification on
+2026-05-08 UTC completed the list:
+
+- Focused render tests for `ConnectionGuide`, `ConnectionDetail`, i18n parity,
+  and credential round-trip.
+- Full project test suite.
+- Lint and format checks.
+- Duplication check.
+- Web bundle rebuild.
+- Browser verification of the Connections CTA and provider-detail controls.

docs/case-studies/issue-27/data/issue-25-comments.json

@@ -0,0 +1 @@
+[]

docs/case-studies/issue-27/data/issue-25.json

@@ -0,0 +1 @@
+{"assignees":[],"author":{"id":"MDQ6VXNlcjE0MzE5MDQ=","is_bot":false,"login":"konard","name":"Konstantin Diachenko"},"body":"At the moment it looks like this:\n\n<img width=\"1824\" height=\"1097\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/6614b628-c26c-4b00-b25b-ed6c8d198a23\" />\n\n<img width=\"686\" height=\"1097\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/8a76b155-e02a-4daa-9754-4f275da3ab4a\" />\n\n1. It should be mobile first, and UI/UX should be in best possible way\n2. All user facing UI must be translated, not partially, but fully.\n3. External services connections should be on separate page like settings, and also there for each separate service we should have item (design in the best way, so it will show if we connected or not, the way of connection and so on), and if we are not connected we for each service we should be redirected to separate screen/page, as each service settings can have quite alot of settings, make sure it is easy for user to get all required data, and it is clearly explained how to get them, so no separate instructions are needed.\n4. The tutorial should be based on actual UI elements, meaning we should make darker everything except next click/tap/press, and clearly describe what to select on each step. So user is guided first to service connections - he selects any service he likes and there he is guided on how to setup this specific service.\n\nUse Apple/Google/Microsoft design guidelines. And make UI design similar to Apple glass with semi transparent UI, use Chakra UI + React.js\n\nDouble check to update our requirements they reflect something different.\n\nWe need to collect data related about the issue to this repository, make sure we compile that data to `./docs/case-studies/issue-{id}` folder, and use it to do deep case study analysis (also make sure to search online for additional facts and data), list of each and all requirements from the issue, and propose possible solutions and solution plans for each requirement (we should also check known existing components/libraries, that solve similar problem or can help in solutions).\n\nPlease plan and execute everything in a single pull request, you have unlimited time and context, as context auto-compacts and you can continue indefinitely, until it is each and every requirement fully addressed, and everything is totally done.\n","createdAt":"2026-05-06T18:23:05Z","labels":[{"id":"LA_kwDOSRd4l88AAAACheWsWA","name":"enhancement","description":"New feature or request","color":"a2eeef"}],"milestone":null,"number":25,"state":"CLOSED","title":"We need to double check that our UI/UX is mobile first and in best possible shape using all best practices","updatedAt":"2026-05-06T20:08:38Z","url":"https://github.com/link-foundation/meta-sovereign/issues/25"}

docs/case-studies/issue-27/data/issue-27-comments.json

@@ -0,0 +1 @@
+[]

docs/case-studies/issue-27/data/issue-27.json

@@ -0,0 +1 @@
+{"assignees":[],"author":{"id":"MDQ6VXNlcjE0MzE5MDQ=","is_bot":false,"login":"konard","name":"Konstantin Diachenko"},"body":"https://github.com/link-foundation/meta-sovereign/issues/25 - here I described my vision, but it was partially ignored.\n\nI expect that on every section, where we show data - we only have small link/button to go to connections sections.\n\nIn connections section it should be clear which service is connected or not, and button for connections. In the connection we should not only have the instructions, but actually all fields we have, and ability to import from exported files/archives, with also ability to connect directly. We now show all UI at most of pages, which is too much. Instead we should do for all pages in similar way inbox -> connections, connections -> vk (and here we should have all instructions + controls on import/connect for each service).\n\nPlease do it maximum user friendly, as the result no features or text should be deleted, but each service connection will now have everything about connection to specific service on its dedicated page.\n\nWe need to download all logs and data related about the issue to this repository, make sure we compile that data to `./docs/case-studies/issue-{id}` folder, and use it to do deep case study analysis (also make sure to search online for additional facts and data), in which we will reconstruct timeline/sequence of events, list of each and all requirements from the issue, find root causes of the each problem, and propose possible solutions and solution plans for each requirement (we should also check known existing components/libraries, that solve similar problem or can help in solutions).\n\nIf there is not enough data to find actual root cause, add debug output and verbose mode if not present, that will allow us to find root cause on next iteration.\n\nIf issue related to any other repository/project, where we can report issues on GitHub, please do so. Each issue must contain reproducible examples, workarounds and suggestions for fix the issue in code.\n\nPlease plan and execute everything in a single pull request, you have unlimited time and context, as context auto-compacts and you can continue indefinitely, until it is each and every requirement fully addressed, and everything is totally done.","createdAt":"2026-05-08T10:52:59Z","labels":[{"id":"LA_kwDOSRd4l88AAAACheWsRw","name":"bug","description":"Something isn't working","color":"d73a4a"}],"milestone":null,"number":27,"state":"OPEN","title":"We need to simplify the UI, and reduce repeating ourselves (using DRY principle in code and UI/UX)","updatedAt":"2026-05-08T10:53:17Z","url":"https://github.com/link-foundation/meta-sovereign/issues/27"}

docs/case-studies/issue-27/data/pr-26-conversation-comments.json

@@ -0,0 +1 @@
+[{"url":"https://api.github.com/repos/link-foundation/meta-sovereign/issues/comments/4391651453","html_url":"https://github.com/link-foundation/meta-sovereign/pull/26#issuecomment-4391651453","issue_url":"https://api.github.com/repos/link-foundation/meta-sovereign/issues/26","id":4391651453,"node_id":"IC_kwDOSRd4l88AAAABBcNIfQ","user":{"login":"konard","id":1431904,"node_id":"MDQ6VXNlcjE0MzE5MDQ=","avatar_url":"https://avatars.githubusercontent.com/u/1431904?v=4","gravatar_id":"","url":"https://api.github.com/users/konard","html_url":"https://github.com/konard","followers_url":"https://api.github.com/users/konard/followers","following_url":"https://api.github.com/users/konard/following{/other_user}","gists_url":"https://api.github.com/users/konard/gists{/gist_id}","starred_url":"https://api.github.com/users/konard/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/konard/subscriptions","organizations_url":"https://api.github.com/users/konard/orgs","repos_url":"https://api.github.com/users/konard/repos","events_url":"https://api.github.com/users/konard/events{/privacy}","received_events_url":"https://api.github.com/users/konard/received_events","type":"User","user_view_type":"public","site_admin":false},"created_at":"2026-05-06T20:04:06Z","updated_at":"2026-05-06T20:04:06Z","body":"## Working session summary\n\nAll CI checks for the latest push have passed. The single `pending` job is `Test (bun on windows-latest)` — UNSTABLE just means CI is still running. Everything passed so far.\n\nPR #26 is finalized and ready for review:\n\n**https://github.com/link-foundation/meta-sovereign/pull/26**\n\nSummary of what landed:\n- **6 atomic commits** mapping to `R-N1`..`R-N12`: AppShell, glass tokens, Connections module, TutorialSpotlight, translation parity, case study + audit cross-refs.\n- **+1 fix commit** for a real UX regression I caught while taking PR screenshots — the spotlight overlay was swallowing taps on the bottom-nav button it was telling the user to tap. Fixed by lifting the rect into the overlay, dropping `pointer-events` on the container, and flipping the dialog to `align-items: flex-start` when the target sits in the lower half (`data-spotlight-side=\"top\"`). Regression test added.\n- **313 tests passing** (up from 312), lint clean, format clean, duplication clean, build clean, all GitHub Actions passing except one Windows-bun job still pending.\n- **PR description** now includes the R-N1..R-N12 table, six screenshots at 360 / 768 / 1280 px, the click-through bug reproducer, and a full test-plan checklist. Marked ready for review.\n\n---\n*This summary was automatically extracted from the AI working session output.*","author_association":"MEMBER","reactions":{"url":"https://api.github.com/repos/link-foundation/meta-sovereign/issues/comments/4391651453/reactions","total_count":0,"+1":0,"-1":0,"laugh":0,"hooray":0,"confused":0,"heart":0,"rocket":0,"eyes":0},"performed_via_github_app":null},{"url":"https://api.github.com/repos/link-foundation/meta-sovereign/issues/comments/4391653545","html_url":"https://github.com/link-foundation/meta-sovereign/pull/26#issuecomment-4391653545","issue_url":"https://api.github.com/repos/link-foundation/meta-sovereign/issues/26","id":4391653545,"node_id":"IC_kwDOSRd4l88AAAABBcNQqQ","user":{"login":"konard","id":1431904,"node_id":"MDQ6VXNlcjE0MzE5MDQ=","avatar_url":"https://avatars.githubusercontent.com/u/1431904?v=4","gravatar_id":"","url":"https://api.github.com/users/konard","html_url":"https://github.com/konard","followers_url":"https://api.github.com/users/konard/followers","following_url":"https://api.github.com/users/konard/following{/other_user}","gists_url":"https://api.github.com/users/konard/gists{/gist_id}","starred_url":"https://api.github.com/users/konard/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/konard/subscriptions","organizations_url":"https://api.github.com/users/konard/orgs","repos_url":"https://api.github.com/users/konard/repos","events_url":"https://api.github.com/users/konard/events{/privacy}","received_events_url":"https://api.github.com/users/konard/received_events","type":"User","user_view_type":"public","site_admin":false},"created_at":"2026-05-06T20:04:19Z","updated_at":"2026-05-06T20:04:19Z","body":"## 🤖 Solution Draft Log\nThis log file contains the complete execution trace of the AI solution draft process.\n\n### 💰 Cost: **$36.793521**\n\n### 📊 **Context and tokens usage:**\n\n**Claude Opus 4.7:** (10 sub-sessions)\n1. 106.2K / 1M (11%) input tokens, 12.8K / 128K (10%) output tokens\n2. 117.6K / 1M (12%) input tokens, 18.6K / 128K (14%) output tokens\n3. 114.9K / 1M (11%) input tokens, 2.6K / 128K (2%) output tokens\n4. 111.0K / 1M (11%) input tokens, 20.5K / 128K (16%) output tokens\n5. 117.7K / 1M (12%) input tokens, 33.1K / 128K (26%) output tokens\n6. 114.8K / 1M (11%) input tokens, 37.9K / 128K (30%) output tokens\n7. 114.9K / 1M (11%) input tokens, 35.2K / 128K (28%) output tokens\n8. 115.6K / 1M (12%) input tokens, 29.3K / 128K (23%) output tokens\n9. 115.8K / 1M (12%) input tokens, 22.9K / 128K (18%) output tokens\n10. 94.1K / 1M (9%) input tokens, 16.6K / 128K (13%) output tokens\n\nTotal: (41.9K new + 1.2M cache writes + 43.5M cache reads) input tokens, 296.1K output tokens, $36.793522 cost\n\n### 🤖 **Models used:**\n- Tool: Anthropic Claude Code\n- Requested: `opus`\n- **Model: Claude Opus 4.7** (`claude-opus-4-7`)\n\n### 📎 **Log file uploaded as Gist** (18248KB)\n- [View complete solution draft log](https://gist.githubusercontent.com/konard/ad718b333aba5962e1a09c4f7903d2bb/raw/7501166e923b55cd4d34385588ce403ad0860bfc/solution-draft-log-pr-1778097850557.txt)\n\n---\n*Now working session is ended, feel free to review and add any feedback on the solution draft.*","author_association":"MEMBER","reactions":{"url":"https://api.github.com/repos/link-foundation/meta-sovereign/issues/comments/4391653545/reactions","total_count":0,"+1":0,"-1":0,"laugh":0,"hooray":0,"confused":0,"heart":0,"rocket":0,"eyes":0},"performed_via_github_app":null},{"url":"https://api.github.com/repos/link-foundation/meta-sovereign/issues/comments/4391674774","html_url":"https://github.com/link-foundation/meta-sovereign/pull/26#issuecomment-4391674774","issue_url":"https://api.github.com/repos/link-foundation/meta-sovereign/issues/26","id":4391674774,"node_id":"IC_kwDOSRd4l88AAAABBcOjlg","user":{"login":"konard","id":1431904,"node_id":"MDQ6VXNlcjE0MzE5MDQ=","avatar_url":"https://avatars.githubusercontent.com/u/1431904?v=4","gravatar_id":"","url":"https://api.github.com/users/konard","html_url":"https://github.com/konard","followers_url":"https://api.github.com/users/konard/followers","following_url":"https://api.github.com/users/konard/following{/other_user}","gists_url":"https://api.github.com/users/konard/gists{/gist_id}","starred_url":"https://api.github.com/users/konard/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/konard/subscriptions","organizations_url":"https://api.github.com/users/konard/orgs","repos_url":"https://api.github.com/users/konard/repos","events_url":"https://api.github.com/users/konard/events{/privacy}","received_events_url":"https://api.github.com/users/konard/received_events","type":"User","user_view_type":"public","site_admin":false},"created_at":"2026-05-06T20:06:44Z","updated_at":"2026-05-06T20:06:44Z","body":"## ✅ Ready to merge\n\nThis pull request is now ready to be merged:\n- All CI checks have passed\n- No merge conflicts\n- No pending changes\n\n---\n*Monitored by hive-mind with --auto-restart-until-mergeable flag*","author_association":"MEMBER","reactions":{"url":"https://api.github.com/repos/link-foundation/meta-sovereign/issues/comments/4391674774/reactions","total_count":0,"+1":0,"-1":0,"laugh":0,"hooray":0,"confused":0,"heart":0,"rocket":0,"eyes":0},"performed_via_github_app":null}]

docs/case-studies/issue-27/data/pr-26-related.json

@@ -0,0 +1 @@
+[]

docs/case-studies/issue-27/data/pr-26-review-comments.json

@@ -0,0 +1 @@
+[]

docs/case-studies/issue-27/data/pr-26-reviews.json

@@ -0,0 +1 @@
+[]