diff --git a/packages/kilo-docs/components/FlowDiagram/index.tsx b/packages/kilo-docs/components/FlowDiagram/index.tsx
index d3eaed578c4..5f18ec04e92 100644
--- a/packages/kilo-docs/components/FlowDiagram/index.tsx
+++ b/packages/kilo-docs/components/FlowDiagram/index.tsx
@@ -68,48 +68,49 @@ export function FlowDiagram({ name, height = "400px" }: { name: string; height?:
   const { ReactFlow, Background, BackgroundVariant } = mod
 
   return (
-    <div
-      style={{
-        height,
-        width: "100%",
-        border: "1px solid rgba(255,255,255,0.08)",
-        borderRadius: "12px",
-        overflow: "hidden",
-        margin: "24px 0",
-      }}
-    >
-      <ReactFlow
-        nodes={diagram.nodes}
-        edges={diagram.edges}
-        fitView
-        fitViewOptions={{ padding: 0.2 }}
-        nodesDraggable={false}
-        nodesConnectable={false}
-        elementsSelectable={false}
-        panOnDrag={false}
-        panOnScroll={false}
-        zoomOnScroll={false}
-        zoomOnPinch={false}
-        zoomOnDoubleClick={false}
-        preventScrolling={false}
-        proOptions={{ hideAttribution: true }}
-        style={{ background: "#08080c" }}
+    <figure style={{ margin: "24px 0" }}>
+      <div
+        style={{
+          height,
+          width: "100%",
+          border: "1px solid rgba(255,255,255,0.08)",
+          borderRadius: "12px",
+          overflow: "hidden",
+        }}
       >
-        <Background variant={BackgroundVariant.Dots} color="rgba(248,160,32,0.15)" gap={20} size={1} />
-      </ReactFlow>
+        <ReactFlow
+          nodes={diagram.nodes}
+          edges={diagram.edges}
+          fitView
+          fitViewOptions={{ padding: 0.2 }}
+          nodesDraggable={false}
+          nodesConnectable={false}
+          elementsSelectable={false}
+          panOnDrag={false}
+          panOnScroll={false}
+          zoomOnScroll={false}
+          zoomOnPinch={false}
+          zoomOnDoubleClick={false}
+          preventScrolling={false}
+          proOptions={{ hideAttribution: true }}
+          style={{ background: "#08080c" }}
+        >
+          <Background variant={BackgroundVariant.Dots} color="rgba(248,160,32,0.15)" gap={20} size={1} />
+        </ReactFlow>
+      </div>
       {diagram.caption && (
-        <p
+        <figcaption
           style={{
             textAlign: "center",
             fontSize: "13px",
             color: "var(--text-muted, #888)",
-            margin: "8px 0 0",
+            marginTop: "8px",
             fontStyle: "italic",
           }}
         >
           {diagram.caption}
-        </p>
+        </figcaption>
       )}
-    </div>
+    </figure>
   )
 }
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/quick-start.md b/packages/kilo-docs/pages/code-with-ai/gastown/quick-start.md
index 487dc6067d2..fb940a31317 100644
--- a/packages/kilo-docs/pages/code-with-ai/gastown/quick-start.md
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/quick-start.md
@@ -43,8 +43,14 @@ Adding a GitHub PAT means all commits, branches, and PRs created by your town's
 {% /callout %}
 
 1. Go to **Town Settings** → **Git & Authentication**
-2. Paste your GitHub Personal Access Token
-3. The token needs `repo` scope (and `workflow` if your repo uses GitHub Actions)
+2. Generate a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) scoped to the repository your town is connected to
+3. Required permissions: **Contents** (read/write), **Pull requests** (read/write), **Metadata** (read)
+4. Optional: add **Actions** (read/write) if your repo uses GitHub Actions workflows
+5. Paste the token and save
+
+{% callout type="info" %}
+Use a fine-grained token scoped to only the repository your town works on. Since agents act autonomously on your behalf, limiting the token's scope reduces risk.
+{% /callout %}
 
 Without a PAT, agents use the GitHub App installation token — functional but shows up as a bot in your git history.
 
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/settings.md b/packages/kilo-docs/pages/code-with-ai/gastown/settings.md
index 9f1e568953f..d95fa6bf147 100644
--- a/packages/kilo-docs/pages/code-with-ai/gastown/settings.md
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/settings.md
@@ -37,16 +37,20 @@ Adding a GitHub PAT ensures that all commits, branches, and PRs created by your
 
 **To add a PAT:**
 1. Go to **Settings** → **Git & Authentication**
-2. Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens)
-3. Required scopes: `repo` (full repository access)
-4. Recommended: also add `workflow` (if your repo uses GitHub Actions)
+2. Generate a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) scoped to the connected repository
+3. Required permissions: **Contents** (read/write), **Pull requests** (read/write), **Metadata** (read)
+4. Optional: add **Actions** (read/write) if your repo uses GitHub Actions workflows
 5. Paste the token and save
 
+{% callout type="info" %}
+Use a fine-grained token limited to only the repository your town is connected to. Agents act autonomously on your behalf, so limiting scope is a best practice.
+{% /callout %}
+
 **What the PAT enables:**
 - Commits and PRs appear as you (your avatar, your username)
 - Agents can use `gh` CLI commands on your behalf
-- Full access to private repositories you own
-- Ability to trigger CI workflows
+- Access to the specific repository you scoped the token to
+- Ability to trigger CI workflows (if Actions permission is granted)
 
 **Without a PAT:**
 - The GitHub App installation token is used (functional but less personal)