[fix](chat,copilot,guide): fix Q&A mismatches, full mutual exclusion, modernize the Guide

Chat Advisor — five question/answer mismatches (a short generic keyword
shadowing a more specific, different intent), all now regression-tested:
- "why not serverless?" hit the privacy blurb ("server" ⊂ "serverless")
- "instal aplikasi offline" hit privacy, not the PWA-install answer
- "daftar semua anti-pattern" (ID "list all") hit privacy
- "what is Cost efficiency?" returned scenario cost/ops, not the QA
- "what is an anti-pattern?" ran a scenario check, not the glossary term
Fixed by narrowing keywords, checking the specific FAQ table before broad
single-word intents, a qaInfo() pre-check on the cost branch, and an
isConceptual() guard routing "what is X" to the glossary.

Full mutual exclusion (owner report): opening any one of {Chat Advisor,
Copilot tour, Guide/Manual, command palette, shortcuts, Compare} now
closes every other — never two open or highlighted at once. Wiring in
App.tsx (derived chatCloseSignal, handleChatOpenChange, handleTourStart,
suspendCopilot); ChatFab self-reports open state + closes on signal;
Copilot stops + hides its launcher when suspended and reports tour start.

Floating-target fix: the tour's final step highlights the fixed Chat
Advisor FAB. A new `floating` flag on that step makes useCopilot skip the
scroll-into-view and CopilotOverlay skip the mobile bottom sheet (which
otherwise covered the very button it points at). Locked in by a test.

Guide / Manual ("Panduan"):
- Content mismatch fixed — §7 "feature map" claimed to cover everything
  but omitted the Chat Advisor and the "Guide me" tour; both added.
- Modernized the dated inline-styled modal into a glass shell with a
  gradient book-mark header, a sticky jump-to-section table of contents,
  numbered gradient section badges, and card sub-sections (new .aa-manual-*
  classes; inline styles removed). The TOC uses scrollIntoView, NOT
  href="#id" anchors, so it never mutates location.hash (reserved for
  share-state). Close-button label → "Close the guide" (test updated).

184 unit tests (up from 175), 14 e2e, 6 guards, bundle within budget all
green. README + DECISIONS updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: programmerShinobi

DECISIONS.md

@@ -557,3 +557,68 @@ Nothing in the underlying architecture changed: `getChatAdapter()`, `ChatAdapter
 `localAdvisorAdapter` (its internal `id: 'local-advisor'`), and the Adapter Pattern itself keep
 their names — "chat" and "advisor" already described the mechanism accurately; only the
 AI-implying product-facing brand needed to go.
+
+## Chat Advisor & Copilot — full mutual exclusion + floating-target fixes, 2026-07-23
+
+Owner report (hand-testing on iPhone SE): the two floating features and the existing overlays could
+visibly collide. Three concrete UI/UX defects, all fixed:
+
+1. **Opening the Chat Advisor covered the "Pandu saya" (Guide me) launcher**, and starting the tour
+   left the chat panel open underneath the tour card. Fixed with **full mutual exclusion**: opening
+   any ONE of {Chat Advisor panel, Copilot tour, Manual/Guide book, command palette, shortcuts,
+   Compare} now closes every other one — never two open or highlighted at once. Wiring lives in
+   `App.tsx`: `handleChatOpenChange` (chat opening clears `overlay`), `handleTourStart` (tour
+   starting bumps `chatCloseSignal` **and** clears `overlay`), a derived `chatCloseSignal` string
+   (changes whenever `overlay` opens or the tour starts — **derived, not a setState-in-effect**, to
+   satisfy the `react-hooks/set-state-in-effect` rule), and `suspendCopilot = chatOpen || overlay
+   !== null` passed to `<Copilot suspended>`. `ChatFab` self-reports its open state via
+   `onOpenChange` and closes itself when `closeSignal` changes; `Copilot` stops the tour + hides its
+   launcher when `suspended`, and calls `onTourStart` when the run begins.
+
+2. **When the tour highlighted the Chat Advisor FAB (last step), the mobile bottom sheet covered the
+   very button it was pointing at**, and the Pre-Flight Check tried to scroll a fixed-position
+   element into view (pointless page motion). Fixed with a `floating: true` flag on that tour step
+   (threaded through `CopilotStep → CopilotStepView`): `useCopilot` skips the scroll adjustment for
+   a floating target, and `CopilotOverlay` skips the mobile bottom-sheet layout for it (falling back
+   to the clamped placement that flips above/beside the target). Verified iPhone-SE: the card sits
+   clear of the FAB (no overlap), spotlight visible.
+
+3. The FAB button itself intentionally **stays visible** during the tour's final step (the step
+   highlights it); only the chat *panel* is force-closed. After the tour ends, clicking the FAB
+   opens the panel normally and re-hides the launcher — verified.
+
+## Chat Advisor Q&A mismatches + Guide (Panduan) modernization, 2026-07-23
+
+More owner hand-testing surfaced answers that didn't match the question, plus a dated-looking Guide.
+
+**Chat Advisor — five question/answer MISMATCHES fixed** (each a short generic keyword shadowing a
+more specific, conceptually different intent — all now covered by regression tests in
+`chat.test.ts`):
+- "why not **serverless**?" returned the privacy blurb — bare `server` is a substring of
+  "serverless"; narrowed to `server call` / `no server` / `a server`.
+- "instal **aplikasi offline**" returned the privacy blurb — `offline` shadowed the PWA-install FAQ;
+  fixed by checking the (more specific, multi-word) FAQ table **before** the broad single-word
+  intents, and dropping `aplikasi offline` from the PWA keywords.
+- "**daftar** semua anti-pattern" returned the privacy blurb — Indonesian `daftar` means "list" (the
+  app has no sign-up), and collided with the catalog's "list all"; removed from privacy keywords.
+- "what is **Cost efficiency**?" returned the scenario's cost/ops numbers instead of the quality
+  attribute — `cost`/`biaya` is a substring of that QA's name; the cost/ops branch now checks
+  `qaInfo()` first.
+- "what is an **anti-pattern**?" (the concept) returned a scenario-specific check — added an
+  `isConceptual()` guard ("what is / define …", without "my/this scenario") that routes conceptual
+  phrasings to the GLOSSARY term for both the anti-pattern and sensitivity intents.
+- The underlying lesson (documented for future intents): **order intents most-specific first**; a
+  bare keyword must never be checked before a multi-word phrase or exact label that contains it.
+
+**Guide / Manual ("Panduan") — content fix + UI modernization:**
+- **Content mismatch fixed.** §7 "the feature map" claimed to cover *everything in the app* but
+  omitted the two features added this session. Added subsections for the **Chat Advisor** (grounded,
+  offline, Advisor-tab-only, not an LLM) and the **"Guide me" interactive tour**, and noted the
+  mutual-exclusion behavior. All other facts re-verified against the current app.
+- **Modernized the dated look** without new deps or bundle regression: the flat inline-styled modal
+  became a glass shell (`aa-glass`) with a gradient book-mark header + subtitle, a **sticky
+  jump-to-section table of contents** (9 pills), numbered gradient section badges, and card-styled
+  sub-sections — all via new `.aa-manual-*` classes in `index.css` (inline styles removed). The TOC
+  uses `scrollIntoView`, **not** `href="#id"` anchors, so it never mutates `location.hash` (which
+  this app reserves for share-state — an anchor jump would have clobbered a share link). Verified
+  desktop + mobile; the close button's aria-label became "Close the guide" (test updated).

README.md

@@ -213,6 +213,11 @@ flowchart LR
 - **Nav-harmony & clean teardown** — switching tabs mid-tour stops it; "Start Over" resets the tour
   alongside the chat; every observer/listener/timer is cleaned up (zero leaks). The launcher and
   the whole overlay are **lazy-loaded**, so the initial JS budget is untouched.
+- **One floating thing at a time** — opening any of {Chat Advisor, this tour, the Guide/Manual,
+  command palette, shortcuts, Compare} closes every other one, so nothing is ever covered by or
+  highlighted behind another. The tour's final step targets the Chat Advisor FAB, a *fixed* control,
+  so that step skips the scroll-into-view + mobile bottom sheet (which would otherwise cover the very
+  button it points at) via a `floating` flag on the step.
 
 ## Run it locally
 

src/App.tsx

@@ -126,6 +126,14 @@ export default function App() {
   const chatResetRef = useRef<(() => void) | null>(null);
   // Registered by the Copilot so "Start Over" hard-resets the guided tour (anti-contamination).
   const copilotResetRef = useRef<(() => void) | null>(null);
+  // Full mutual exclusion between every floating/overlay UI (owner report): the Chat Advisor panel
+  // and the Copilot tour. `chatOpen` mirrors ChatFab's own open state (it self-reports via
+  // onOpenChange — App can't set it directly). `chatCloseTick` is bumped to force ChatFab closed
+  // from outside (tour starting, or any `overlay` opening); ChatFab watches it and calls its own
+  // setOpen(false) in response. The `overlay` half of this (Manual/Guide · palette · shortcuts ·
+  // Compare) is wired in just below, once `overlay`/`setOverlay` exist.
+  const [chatOpen, setChatOpen] = useState(false);
+  const [chatCloseTick, setChatCloseTick] = useState(0);
 
   const scenario: ScenarioState = { v: 1, mode, lang, levels, selections, overrides };
   const exportInput: ExportInput = { levels, overrides, selections: effective, lang };
@@ -171,6 +179,24 @@ export default function App() {
 
   const { status: exportStatus, setStatus: setExportStatus, run } = useExportActions(exportInput, scenario, weights);
   const [overlay, setOverlay] = useState<'palette' | 'shortcuts' | 'manual' | 'compare' | null>(null);
+
+  // Finish the mutual-exclusion wiring (owner report: opening any ONE of Chat Advisor / Copilot
+  // tour / Manual-Guide / palette / shortcuts / Compare must close every other one — never two open
+  // or highlighted together). `chatCloseSignal` is a plain DERIVED value (no effect, no
+  // setState-in-effect) that changes whenever `overlay` opens OR the tour starts — ChatFab watches
+  // it and closes itself in response. Opening chat or starting the tour closes `overlay` directly
+  // (both are ordinary event handlers, not effects).
+  const chatCloseSignal = `${overlay ?? ''}|${chatCloseTick}`;
+  const handleChatOpenChange = (open: boolean) => {
+    setChatOpen(open);
+    if (open) setOverlay(null);
+  };
+  const handleTourStart = () => {
+    setChatCloseTick((n) => n + 1);
+    setOverlay(null);
+  };
+  const suspendCopilot = chatOpen || overlay !== null;
+
   const [snapA, setSnapA] = usePersistedState<ScenarioState | null>('aa.snapA', null);
   const [snapB, setSnapB] = usePersistedState<ScenarioState | null>('aa.snapB', null);
 
@@ -254,7 +280,12 @@ export default function App() {
         unmounts it; conversation history still persists (localStorage) and resumes on return. */}
     {FEATURES.chat && mainView === 'advisor' && (
       <Suspense fallback={null}>
-        <ChatFab contextInput={{ levels, overrides, mode, lang }} registerReset={(fn) => (chatResetRef.current = fn)} />
+        <ChatFab
+          contextInput={{ levels, overrides, mode, lang }}
+          registerReset={(fn) => (chatResetRef.current = fn)}
+          onOpenChange={handleChatOpenChange}
+          closeSignal={chatCloseSignal}
+        />
       </Suspense>
     )}
     {/* Interactive Copilot / guided tutorial (Phase 3) — a lazy, pluggable feature module. */}
@@ -265,6 +296,8 @@ export default function App() {
         lang={lang}
         topPick={rankings.D1[0]?.name}
         registerReset={(fn) => (copilotResetRef.current = fn)}
+        suspended={suspendCopilot}
+        onTourStart={handleTourStart}
       />
     </Suspense>
     <MobileChrome mainView={mainView} onNavigate={navigate} theme={theme} onToggleTheme={toggleTheme} mode={mode} onSetMode={setMode} />

src/components/chat/ChatFab.tsx

@@ -11,11 +11,19 @@ interface Props {
   contextInput: ChatContextInput;
   /** App registers the mounted chat's reset() so "Start Over" wipes it in-tab. */
   registerReset: (reset: (() => void) | null) => void;
+  /** Reports open/close so App can mutually exclude every other overlay/floating feature (owner
+   *  report: nothing may ever be visibly open/highlighted at the same time as anything else). */
+  onOpenChange?: (open: boolean) => void;
+  /** A value that CHANGES whenever App wants this panel closed from outside (the Copilot tour
+   *  starting, or the Manual/Guide · palette · shortcuts · Compare overlay opening) — closes the
+   *  panel so it never covers (or gets covered by) another one. The FAB button itself stays
+   *  visible: the tour's own last step highlights it. */
+  closeSignal?: string | number;
 }
 
 // The floating chat launcher (Advisor "Chat Advisor"). Toggles the lazy panel; keeps its own open
 // state. Esc closes. Opening never resets chat; closing keeps the session (persisted).
-export function ChatFab({ contextInput, registerReset }: Readonly<Props>) {
+export function ChatFab({ contextInput, registerReset, onOpenChange, closeSignal }: Readonly<Props>) {
   const { t } = useI18n();
   const [open, setOpen] = useState(false);
   const [everOpened, setEverOpened] = useState(false);
@@ -30,6 +38,21 @@ export function ChatFab({ contextInput, registerReset }: Readonly<Props>) {
     return () => window.removeEventListener('keydown', onKey);
   }, [open]);
 
+  useEffect(() => {
+    onOpenChange?.(open);
+  }, [open, onOpenChange]);
+
+  // Mutual exclusion (owner report): the Copilot tour starting closes this panel. Skips the very
+  // first render so mounting never force-closes an already-open panel.
+  const mounted = useRef(false);
+  useEffect(() => {
+    if (!mounted.current) {
+      mounted.current = true;
+      return;
+    }
+    setOpen(false);
+  }, [closeSignal]);
+
   const toggle = () => {
     setOpen((v) => !v);
     setEverOpened(true);