Merge pull request #66 from programmerShinobi/feat/phase3-chat-advisor

[feat](insights): group the landing into four lenses + three activities

Author: programmerShinobi

scripts/check-bundle-size.mjs

@@ -16,7 +16,7 @@ import { gzipSync } from 'node:zlib';
 // This reads the real initial set from index.html rather than guessing by filename, so a new lazy or
 // shared async chunk can't silently be mis-counted. Headroom catches a real regression; raise the
 // budgets deliberately (with a note) if the app grows.
-const JS_INITIAL_BUDGET_KB = 121; // 120→121 for Phase 3 (chat + copilot) 2026-07-19: both features are LAZY chunks; the only initial delta is their dynamic-import stubs + a few refs of wiring (~0.3kB gzip, negligible FCP). NFR ceiling is far higher.
+const JS_INITIAL_BUDGET_KB = 122; // 120→121 for Phase 3 (chat + copilot) 2026-07-19: both features are LAZY chunks; the only initial delta is their dynamic-import stubs + a few refs of wiring (~0.3kB gzip, negligible FCP). 121→122 on 2026-07-25 for the Insights landing's grouping + "open this when" copy: those 11 dict keys are only READ on a lazy tab, but `dict` is one object literal, so Vite cannot tree-shake properties and every key costs first paint wherever it is used — an accepted, known property of this i18n design, paid here as ~0.6kB gzip. NFR ceiling is far higher.
 const JS_TOTAL_BUDGET_KB = 284; // raised 200→260 (Insights bilingualisation 2026-07-15); 260→268 for the Phase 3 Chat Advisor 2026-07-19 (adapter + hook + panel, all in a LAZY chunk — the FAB is lazy too, so the initial budget is untouched); 268→278 for the 2026-07-23 scenario-coverage expansion (cost/ops, risk catalog, sensitivity, migration, dimension/factor/QA lookups, app-usage FAQ — all pure data-driven text in the same lazy chunk; NFR cap is 300); 278→281 for the 2026-07-25 Chat Advisor capability browser + "How to use this" pane (bilingual help copy, same lazy chunk — initial JS unchanged at 120.8/121, so first paint is unaffected); 281→284 for the 2026-07-25 role-based "Start here" section in the Guide (six bilingual role paths — prose only, in the already-lazy ManualBook chunk that loads on demand; initial JS still 120.8/121, NFR cap 300)
 const CSS_BUDGET_KB = 29; // 25→27 (Fase 2g polish 2026-07-18); 27→29 for Phase 3 2026-07-19 (chat panel + copilot overlay/launcher/Dos-Don'ts cards); still under the ~30kB NFR ceiling
 

src/components/insights/LearnView.test.tsx

@@ -19,6 +19,24 @@ describe('LearnView', () => {
     return { onOpenAdvisor, onLoadLab };
   };
 
+  // The landing groups its seven sections into "four lenses on the same 21 architectures" + "three
+  // activities". Rendering them as one flat grid read as seven separate libraries to get through —
+  // wrong, and the main reason the tab felt daunting. These pin the structure and the routing line.
+  it('groups the landing into the four lenses and the three activities, never one flat list', () => {
+    render();
+    expect(screen.getByRole('heading', { name: 'Read about the architectures' })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { name: 'Build the skill' })).toBeInTheDocument();
+    // The point of the grouping: state that the four are one subject read four ways.
+    expect(screen.getByText(/Four ways of reading the same 21 architectures/)).toBeInTheDocument();
+  });
+
+  it('tells the reader when each section is the right one to open, not just what it holds', () => {
+    render();
+    // One "Open this when…" line per section: the descriptions say what a section CONTAINS, which
+    // is not the question someone staring at seven cards is actually asking.
+    expect(screen.getAllByText(/^Open this when/)).toHaveLength(AVAILABLE_SECTIONS.length);
+  });
+
   it('every architecture has a Catalog, Playbook, Review, and Library entry (parity with the model)', () => {
     for (const dim of DIMENSION_ORDER) {
       for (const opt of DIMENSIONS[dim].options) {

src/components/insights/LearnView.tsx

@@ -17,7 +17,7 @@ import {
   IconScale,
 } from '@tabler/icons-react';
 import { useI18n } from '../../i18n/I18nContext';
-import { AVAILABLE_SECTIONS, sectionMeta } from '../../config/sections';
+import { AVAILABLE_SECTIONS, sectionMeta, SECTION_GROUPS, SECTION_WHEN } from '../../config/sections';
 import { contentBySection, contentBySlug, docBody, docTitle, docTldr } from '../../lib/content';
 import { renderMarkdown } from '../../lib/markdown';
 import { DIMENSIONS, DIMENSION_ORDER } from '../../config/dimensions';
@@ -599,39 +599,58 @@ export default function LearnView({ onOpenAdvisor, onLoadLab, initialTarget }: P
       <h1 style={{ fontSize: 'var(--aa-fs-xl)', fontWeight: 600, marginBottom: '6px' }}>{t('learn.title')}</h1>
       <p style={{ fontSize: '13px', color: 'var(--color-text-secondary)', marginBottom: '6px', maxWidth: '72ch' }}>{t('learn.intro')}</p>
       <p style={{ fontSize: '12px', color: 'var(--color-text-tertiary)', marginBottom: '18px' }}>{t('learn.readingHint')}</p>
-      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit,minmax(min(260px, 100%), 1fr))', gap: '14px' }}>
-        {AVAILABLE_SECTIONS.map((s) => {
-          const Icon = s.icon;
-          const isLens = (LENSES as string[]).includes(s.id);
-          const guides = s.id === 'catalog' ? 0 : contentBySection(s.id).length;
-          return (
-            <button key={s.id} type="button" className="learn-card aa-reveal" style={{ ...cardBase, padding: 'var(--aa-panel-pad)', display: 'flex', flexDirection: 'column', gap: '10px' }} onClick={() => setSection(s.id)}>
-              <span className="learn-chip">
-                <Icon size={19} aria-hidden />
-              </span>
-              <span style={{ fontSize: '16px', fontWeight: 600 }}>{t(s.label)}</span>
-              <span style={{ fontSize: '12.5px', color: 'var(--color-text-secondary)', lineHeight: 1.5, flexGrow: 1 }}>{t(s.desc)}</span>
-              <span style={{ display: 'flex', alignItems: 'center', gap: '5px', fontSize: '12px', color: 'var(--color-text-info)', fontWeight: 600, flexWrap: 'wrap' }}>
-                {isLens ? (
-                  <>
-                    {totalArchitectures} {t('learn.architectures')}
-                    {guides > 0 && <span style={{ color: 'var(--color-text-tertiary)' }}>· {guides} {t('learn.guidesWord')}</span>}
-                  </>
-                ) : s.id === 'roadmap' ? (
-                  <>{LEARNING_PATHS.length} {t('learn.paths')}</>
-                ) : s.id === 'academy' ? (
-                  <>{ACADEMY_QUIZZES.length} {t('learn.modules')}</>
-                ) : s.id === 'lab' ? (
-                  <>{LAB_EXPERIMENTS.length} {t('learn.experiments')}</>
-                ) : (
-                  <>{guides} {t('learn.articles')}</>
-                )}
-                <IconArrowRight size={13} aria-hidden />
-              </span>
-            </button>
-          );
-        })}
-      </div>
+
+      {/* The seven sections are NOT seven peers, and rendering them as one flat grid was the single
+          biggest source of confusion here: four of them are the SAME 21 architectures read from four
+          angles, while the other three are activities you do. Someone who cannot see that boundary
+          reads "Catalog, Playbook, Review, Library" as four separate libraries to get through, which
+          is both wrong and daunting. Grouping states the structure the codebase already knew. */}
+      {SECTION_GROUPS.map((group) => {
+        const sections = AVAILABLE_SECTIONS.filter((s) => group.ids.includes(s.id));
+        if (sections.length === 0) return null;
+        return (
+          <section key={group.id} style={{ marginBottom: '26px' }}>
+            <h2 style={{ fontSize: '14px', fontWeight: 600, marginBottom: '3px' }}>{t(group.label)}</h2>
+            <p style={{ fontSize: '12.5px', color: 'var(--color-text-secondary)', lineHeight: 1.5, marginBottom: '12px', maxWidth: '72ch' }}>{t(group.desc)}</p>
+            <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit,minmax(min(260px, 100%), 1fr))', gap: '14px' }}>
+              {sections.map((s) => {
+                const Icon = s.icon;
+                const isLens = (LENSES as string[]).includes(s.id);
+                const guides = s.id === 'catalog' ? 0 : contentBySection(s.id).length;
+                return (
+                  <button key={s.id} type="button" className="learn-card aa-reveal" style={{ ...cardBase, padding: 'var(--aa-panel-pad)', display: 'flex', flexDirection: 'column', gap: '10px' }} onClick={() => setSection(s.id)}>
+                    <span className="learn-chip">
+                      <Icon size={19} aria-hidden />
+                    </span>
+                    <span style={{ fontSize: '16px', fontWeight: 600 }}>{t(s.label)}</span>
+                    <span style={{ fontSize: '12.5px', color: 'var(--color-text-secondary)', lineHeight: 1.5 }}>{t(s.desc)}</span>
+                    {/* "Open this when…" — the descriptions say what a section CONTAINS; this says
+                        when it is the right one to pick, which is the actual question being asked. */}
+                    <span style={{ fontSize: '12px', color: 'var(--color-text-tertiary)', lineHeight: 1.5, flexGrow: 1 }}>{t(SECTION_WHEN[s.id])}</span>
+                    <span style={{ display: 'flex', alignItems: 'center', gap: '5px', fontSize: '12px', color: 'var(--color-text-info)', fontWeight: 600, flexWrap: 'wrap' }}>
+                      {isLens ? (
+                        <>
+                          {totalArchitectures} {t('learn.architectures')}
+                          {guides > 0 && <span style={{ color: 'var(--color-text-tertiary)' }}>· {guides} {t('learn.guidesWord')}</span>}
+                        </>
+                      ) : s.id === 'roadmap' ? (
+                        <>{LEARNING_PATHS.length} {t('learn.paths')}</>
+                      ) : s.id === 'academy' ? (
+                        <>{ACADEMY_QUIZZES.length} {t('learn.modules')}</>
+                      ) : s.id === 'lab' ? (
+                        <>{LAB_EXPERIMENTS.length} {t('learn.experiments')}</>
+                      ) : (
+                        <>{guides} {t('learn.articles')}</>
+                      )}
+                      <IconArrowRight size={13} aria-hidden />
+                    </span>
+                  </button>
+                );
+              })}
+            </div>
+          </section>
+        );
+      })}
     </div>
   );
 }

src/components/overlays/ManualBook.tsx

@@ -386,10 +386,22 @@ export function ManualBook({ open, onClose, levels, weights }: Props) {
             'Bagian analisis menambah radar trade-off, sensitivitas ("perubahan tunggal apa yang membalik pilihan?"), pembanding skenario pin-A/B, peringatan anti-pattern, jalur migrasi, daftar risiko, fitness function, indikator biaya/operasional, dan sketsa C4.',
           )}
 
-          <strong className="aa-manual-subhead">{L('Insights — seven ways into the same knowledge', 'Insights — tujuh pintu ke pengetahuan yang sama')}</strong>
+          <strong className="aa-manual-subhead">{L('Insights — four lenses plus three ways to practise', 'Wawasan — empat lensa plus tiga cara berlatih')}</strong>
           {p(
-            'Catalog (discover each of the 21 architectures), Playbook (step-by-step implementation), Review (structured evaluation with a verdict), Library (reference: concepts & terminology + evergreen articles), Roadmap (learning paths), Academy (quizzes with explanations), and Lab (experiments that load a prepared scenario into the real engine). Everything is bilingual and cross-linked.',
-            'Katalog (kenali 21 arsitektur), Playbook (implementasi langkah demi langkah), Review (evaluasi terstruktur dengan verdict), Pustaka (referensi: konsep & terminologi + artikel evergreen), Peta Belajar (jalur belajar), Akademi (kuis dengan penjelasan), dan Lab (eksperimen yang memuat skenario siap pakai ke mesin sungguhan). Semuanya dwibahasa dan saling bertaut.',
+            'The seven cards on this tab are not seven separate bodies of material, and reading them that way is what makes the tab look enormous. Four of them — Catalog, Playbook, Review and Library — are the SAME 21 architectures read from four angles: every architecture appears in all four, and each page has a switcher to jump between them. The other three are things you do rather than read.',
+            'Tujuh kartu di tab ini bukan tujuh kumpulan materi yang terpisah, dan membacanya seperti itulah yang membuat tab ini terasa raksasa. Empat di antaranya — Katalog, Playbook, Review, dan Pustaka — adalah 21 arsitektur YANG SAMA dibaca dari empat sudut: tiap arsitektur muncul di keempatnya, dan tiap halaman punya pengalih untuk melompat antar sudut. Tiga sisanya adalah hal yang Anda kerjakan, bukan dibaca.',
+          )}
+          {p(
+            'The four lenses, by the question they answer: Catalog — what is this and where is it used, when you do not yet recognise the name. Playbook — how do I actually build it, once the decision is made: prerequisites, ordered steps, best practices and the pitfalls people hit. Review — how do these two compare, when you are weighing options: pros and cons, performance, scalability, developer experience, and a verdict. Library — what does this term mean, for definitions, concepts and standards.',
+            'Empat lensa itu, menurut pertanyaan yang dijawabnya: Katalog — ini apa dan dipakai di mana, ketika Anda belum mengenali namanya. Playbook — bagaimana membangunnya, setelah keputusan diambil: prasyarat, langkah berurutan, praktik terbaik, dan jebakan yang sering ditemui. Review — bagaimana kedua opsi ini dibandingkan, ketika Anda sedang menimbang: pro dan kontra, performa, skalabilitas, pengalaman pengembang, dan sebuah verdik. Pustaka — istilah ini artinya apa, untuk definisi, konsep, dan standar.',
+          )}
+          {p(
+            'The three practice sections: Roadmap gives you an ordered route through the lenses, for when choosing a starting point is itself the obstacle. Academy asks questions and marks them on your device, so you find out what you actually retained rather than what felt familiar; a wrong answer links back to the page that teaches it. Lab is the one to open if you learn by doing — each experiment loads a prepared scenario into the real scoring engine, so you change one factor and watch the ranking move, which teaches a trade-off far better than a paragraph about it.',
+            'Tiga seksi latihan: Peta Belajar memberi rute berurutan menyusuri lensa-lensanya, untuk saat memilih titik mulai justru jadi hambatannya. Akademi mengajukan soal dan menilainya di perangkat Anda, sehingga Anda tahu apa yang benar-benar tersimpan, bukan apa yang sekadar terasa familier; jawaban salah bertaut balik ke halaman yang mengajarkannya. Lab adalah yang dibuka kalau Anda belajar dengan mempraktikkan — tiap eksperimen memuat skenario siap pakai ke mesin skor sungguhan, jadi Anda ubah satu faktor lalu melihat peringkatnya bergerak, dan itu mengajarkan sebuah pertukaran jauh lebih baik daripada satu paragraf tentangnya.',
+          )}
+          {p(
+            'Two things worth knowing before you start. The Guided / Expert switch in the header changes the reading depth everywhere on this tab: newcomers get plain language, experts get mechanism, evidence and cited sources. And the articles themselves are in English — a deliberate product decision, since the primary literature is — while all the navigation around them follows your chosen language.',
+            'Dua hal yang perlu diketahui sebelum mulai. Sakelar Terpandu / Ahli di header mengubah kedalaman bacaan di seluruh tab ini: pemula mendapat bahasa sederhana, ahli mendapat mekanisme, bukti, dan sumber terkutip. Dan artikel-artikelnya sendiri berbahasa Inggris — keputusan produk yang disengaja, karena literatur primernya memang begitu — sementara seluruh navigasi di sekelilingnya mengikuti bahasa pilihan Anda.',
           )}
 
           <strong className="aa-manual-subhead">{L('Save, export & share', 'Simpan, ekspor & bagikan')}</strong>

src/config/sections.ts

@@ -35,6 +35,43 @@ export const SECTIONS: SectionMeta[] = [
 
 export const AVAILABLE_SECTIONS = SECTIONS.filter((s) => s.available);
 
+/**
+ * The two kinds of section, made explicit for the Insights landing.
+ *
+ * Catalog / Playbook / Review / Library are FOUR ANGLES ON THE SAME 21 ARCHITECTURES — the same
+ * subject read four ways, not four separate libraries. Roadmap / Academy / Lab are activities you
+ * do. Presenting all seven as one flat grid hid that boundary and made the tab look like seven
+ * bodies of material to get through, which is both wrong and discouraging.
+ */
+export interface SectionGroup {
+  id: 'lenses' | 'practice';
+  label: DictKey;
+  desc: DictKey;
+  ids: SectionId[];
+}
+
+export const SECTION_GROUPS: SectionGroup[] = [
+  { id: 'lenses', label: 'learn.group.lenses', desc: 'learn.group.lenses.desc', ids: ['catalog', 'playbook', 'review', 'library'] },
+  { id: 'practice', label: 'learn.group.practice', desc: 'learn.group.practice.desc', ids: ['roadmap', 'academy', 'lab'] },
+];
+
+/**
+ * "Open this when…" — one line per section naming the SITUATION it answers.
+ *
+ * The `desc` fields say what a section contains; that is not the question a person on this page is
+ * asking. They are asking which one to click, and that is decided by what they are trying to do
+ * right now, so these are phrased as circumstances rather than contents.
+ */
+export const SECTION_WHEN: Record<SectionId, DictKey> = {
+  catalog: 'learn.when.catalog',
+  playbook: 'learn.when.playbook',
+  review: 'learn.when.review',
+  library: 'learn.when.library',
+  roadmap: 'learn.when.roadmap',
+  academy: 'learn.when.academy',
+  lab: 'learn.when.lab',
+};
+
 export function sectionMeta(id: SectionId): SectionMeta | undefined {
   return SECTIONS.find((s) => s.id === id);
 }