fix: address PR #1157 review feedback (docs/security/UX)

CodeRabbit + Copilot review fixes that don't touch the generated tool
reference. Generator change + regenerated pages come in a follow-up
commit.

docs:
- guides/uv-setup.md: Python requirement was wrongly 3.12+; the server
  pyproject declares >=3.10. Verify command + body updated to 3.10+.
  Homebrew tip retains 3.12 as a reasonable default.
- getting-started/index.md: drop "(coming soon)" placeholders for
  Your First Prompt and Choosing an MCP Client — both pages exist
  in this PR. Setup Wizard remains "coming soon" (not in this PR).
- .github/ISSUE_TEMPLATE/bug_report.yml: troubleshooting link pointed
  at /guides/cursor (deleted earlier in this branch); now points at
  /guides/troubleshooting which is where that content lives.

components:
- CopyButton: track setTimeout in a useRef, clear it on unmount and
  before scheduling a new one. Prevents React "setState on unmounted
  component" warnings and stops timer-stacking on rapid clicks.
- HomeArchitecture diagram <div>: now role="img" with a descriptive
  aria-label that explains the layer flow, so assistive tech actually
  announces the diagram instead of skipping it.

workflows (security):
- docs-deploy.yml, docs-generate.yml: add `persist-credentials: false`
  on actions/checkout — these jobs never push, so the token shouldn't
  linger in the checked-out worktree (zizmor `artipacked` warning).
- sync-releases.yml:
  - Workflow-level permissions narrowed to `contents: read`; the
    `sync` job opts into `contents: write` itself. `drift-check`
    stays read-only.
  - drift-check job: was gated on `pull_request` but the workflow had
    no pull_request trigger — unreachable code. Added a paths-scoped
    pull_request trigger so PRs touching the sync script or the synced
    docs run the check.
  - `sync` job retains `persist-credentials: true` (it pushes back).
  - drift-check checkout gets `persist-credentials: false`.

CodeRabbit comments NOT addressed in this PR and why:
- execute_menu_item 'exists' mode, script_apply_edits malformed JSON,
  find_gameobjects empty param descriptions: all live in the Python
  tool's source description string under Server/src/services/tools/.
  Fixing upstream is a separate code PR; the generator faithfully
  renders whatever source provides.
- React 18.3.1 / Docusaurus 3.10.1 bump: out of scope for this docs
  PR; the lockfile already permits the latest 18.x, and a Docusaurus
  minor bump is a separate dependency PR.
- robots.txt sitemap 404 check: will resolve as soon as Pages serves
  the site on the canonical URL. Not a real bug.
- sidebars.js duplicate roadmap: /architecture/roadmap is the 2026
  feature deep-research; /architecture/project-roadmap is the wiki
  living roadmap. Two distinct docs, intentional.
- scripting_ext group blurb: comes from the registry TOOL_GROUPS map;
  wording tweak not worth touching in a docs PR.

Author: Scriptwonder

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -10,7 +10,7 @@ body:
 
         **Before filing:**
         - Search [existing issues](https://github.com/CoplayDev/unity-mcp/issues?q=is%3Aissue) to avoid duplicates
-        - Check the [troubleshooting docs](https://coplaydev.github.io/unity-mcp/guides/cursor) and [setup wiki](https://github.com/CoplayDev/unity-mcp/wiki)
+        - Check the [troubleshooting docs](https://coplaydev.github.io/unity-mcp/guides/troubleshooting) and [setup wiki](https://github.com/CoplayDev/unity-mcp/wiki)
 
   - type: textarea
     id: what-happened

.github/workflows/docs-deploy.yml

@@ -49,6 +49,9 @@ jobs:
           # can resolve real per-file commit metadata. Shallow clones make every
           # page report the latest commit instead.
           fetch-depth: 0
+          # No push back from this workflow — the deploy uses the Pages
+          # OIDC token issued by actions/deploy-pages, not the repo token.
+          persist-credentials: false
 
       - name: Setup Node
         uses: actions/setup-node@v4

.github/workflows/docs-generate.yml

@@ -38,6 +38,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4

.github/workflows/sync-releases.yml

@@ -22,12 +22,21 @@ on:
   release:
     types: [published, edited, unpublished, deleted]
   workflow_dispatch: {}
+  pull_request:
+    paths:
+      - tools/sync_release_notes.py
+      - website/docs/releases.md
+      - README.md
+      - .github/workflows/sync-releases.yml
   schedule:
     # 11:00 UTC daily — picks up any out-of-band edits to release bodies.
     - cron: '0 11 * * *'
 
+# Least-privilege at the workflow level. The `sync` job below opts into
+# `contents: write` explicitly because it commits + pushes; `drift-check`
+# only reads so it stays read-only.
 permissions:
-  contents: write
+  contents: read
 
 concurrency:
   group: docs-sync-releases
@@ -36,14 +45,19 @@ concurrency:
 jobs:
   sync:
     name: Sync release notes
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - name: Checkout beta
         uses: actions/checkout@v4
         with:
           ref: beta
           # Full history so the commit lands on a fresh ref tip.
           fetch-depth: 0
+          # `sync` needs to push back, so the token must persist here.
+          persist-credentials: true
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Set up Python
@@ -76,6 +90,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'

website/docs/getting-started/index.md

@@ -30,9 +30,9 @@ MCP for Unity bridges AI assistants — Claude, Codex, VS Code, local LLMs, and
 ## Next steps
 
 - **[Install](./install.md)** — Add the Unity package, install the Python server, and connect your first MCP client.
+- **[Your First Prompt](./first-prompt.md)** — End-to-end "build me a red cube" tutorial.
+- **[Choosing an MCP Client](./clients.md)** — A capability matrix across all supported clients.
 - **Setup Wizard** *(coming soon)* — Walk through the first-run experience.
-- **Your First Prompt** *(coming soon)* — End-to-end "build me a red cube" tutorial.
-- **Choosing an MCP Client** *(coming soon)* — A capability matrix across all supported clients.
 
 ---
 

website/docs/guides/uv-setup.md

@@ -21,12 +21,12 @@ Clients like Claude Code or JetBrains Rider can get confused if you switch from
 
 ## Requirements
 
-You need **Python 3.12+** and the **`uv`** package manager.
+You need **Python 3.10+** and the **`uv`** package manager.
 
 ### Verify
 
 ```bash
-python3 --version   # should be 3.12+
+python3 --version   # should be 3.10+
 uv --version        # should print a version like "uv 0.x"
 ```
 
@@ -38,7 +38,7 @@ uv --version        # should print a version like "uv 0.x"
 # Option A: Official installer (recommended)
 # Download from https://www.python.org/downloads/
 
-# Option B: Homebrew
+# Option B: Homebrew (3.12 is the latest LTS as of writing; 3.10 also works)
 brew install python@3.12
 ```
 

website/src/components/CopyButton/index.js

@@ -1,4 +1,4 @@
-import React, { useState } from 'react';
+import React, { useState, useRef, useEffect } from 'react';
 import styles from './styles.module.css';
 
 /**
@@ -9,6 +9,13 @@ import styles from './styles.module.css';
  */
 export default function CopyButton({ text, label = 'Copy', className }) {
   const [copied, setCopied] = useState(false);
+  // Timer ref so rapid repeated clicks don't stack pending resets and
+  // an unmount mid-cooldown doesn't fire setCopied on a dead component.
+  const timerRef = useRef(null);
+
+  useEffect(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+  }, []);
 
   const onClick = async () => {
     try {
@@ -27,7 +34,8 @@ export default function CopyButton({ text, label = 'Copy', className }) {
         document.body.removeChild(ta);
       }
       setCopied(true);
-      setTimeout(() => setCopied(false), 1500);
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => setCopied(false), 1500);
     } catch {
       // swallow — the user can still select-and-copy the rendered text
     }

website/src/components/HomeArchitecture/index.js

@@ -16,7 +16,11 @@ export default function HomeArchitecture() {
           </p>
         </div>
 
-        <div className={styles.diagram} aria-label="MCP for Unity architecture diagram">
+        <div
+          className={styles.diagram}
+          role="img"
+          aria-label="MCP for Unity architecture diagram: MCP client connects to the Python server over stdio or HTTP, which talks to the Unity Editor plugin over WebSocket."
+        >
           <Stage
             kicker="LAYER 01"
             title="MCP Client"