feat: config & onboarding — each teammate connects their own Gitea (Phase A)

The foundation for a shareable team build. Replaces the .env.local-only dev config
with a real, per-teammate connection flow.

main:
- config-store.ts: token encrypted at rest via Electron safeStorage (OS keychain),
  config JSON in userData. Token lives only in main; renderer gets everything but.
- resolveConfig: saved config > .env.local (dev) > null; ignored under COMMITEA_E2E.
  pm-state repo defaults to `${repo}-pm-state`. resetClients() re-reads on change so
  saving config takes effect without a restart. gitea:status gains `demo` (e2e).
- IPC: config:get (no token), config:test (authed read validates token+repo),
  config:set (encrypt+save+reset), config:clear. Model bridge reads config.modelUrl
  and probes reachability — chat is "configured" only if a model actually answers;
  localhost default is dev-only (app.isPackaged gate).

renderer:
- ConnectScreen: real onboarding form (URL/owner/repo/PAT/optional model) → test →
  save. AppShell gates on it: demo → shell (fixtures/e2e); configured → shell (real);
  else → connect. Settings Connection card is real (repo/url/model/sidecar) with
  Reconfigure + Disconnect. Chat cleanly disables with a "no model" state instead of
  the scripted canned reply.

Verified: main + desktop typecheck clean, 14 fixture e2e green (demo mode unchanged),
live onboarding e2e: fresh app → connect form → validated PAT → real board (24 done /
10 open). COMMITEA_NO_ENV_LOCAL + COMMITEA_USERDATA are test hooks for the onboarding path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/desktop/src/renderer/src/components/screens/connect-screen.tsx

@@ -0,0 +1,117 @@
+import React from 'react'
+
+import type { PublicConfig } from '../../global.js'
+import logoIcon from '../../design/assets/logo-icon.png'
+import { Button, Card, Input } from '../ui/index.js'
+
+/**
+ * Real onboarding — each teammate connects their own Gitea with a personal access
+ * token. The token is validated (an authed read on the repo) then saved encrypted
+ * in the main process (never exposed to this renderer). Optional model URL wires
+ * Reginald; leave it blank and chat simply stays off.
+ */
+export function ConnectScreen({ onConnected, existing }: { onConnected: () => void; existing?: PublicConfig | null }) {
+  const [baseUrl, setBaseUrl] = React.useState(existing?.baseUrl ?? 'https://gitea.stephenmann.io')
+  const [owner, setOwner] = React.useState(existing?.owner ?? '')
+  const [repo, setRepo] = React.useState(existing?.repo ?? '')
+  const [token, setToken] = React.useState('')
+  const [modelUrl, setModelUrl] = React.useState(existing?.modelUrl ?? '')
+  const [state, setState] = React.useState<'idle' | 'testing' | 'saving'>('idle')
+  const [error, setError] = React.useState<string | null>(null)
+
+  const cfg = () => ({ baseUrl, owner, repo, token, modelUrl: modelUrl.trim() || undefined })
+  const ready = baseUrl.trim() && owner.trim() && repo.trim() && (token.trim() || existing?.hasToken)
+
+  const connect = async () => {
+    setError(null)
+    setState('testing')
+    // reuse the saved token when editing and the field is left blank
+    const payload = token.trim() ? cfg() : { ...cfg(), token: '' }
+    if (token.trim()) {
+      const test = await window.commitea.config.test(cfg()).catch(() => ({ ok: false, error: 'unreachable' }))
+      if (!test.ok) {
+        setState('idle')
+        setError(
+          test.error === '404'
+            ? "Couldn't find that repo — check owner/name and that the token can see it."
+            : test.error === '401' || test.error === '403'
+              ? 'The token was rejected — check it has repo + issue scopes.'
+              : `Connection failed${test.error ? ` (${test.error})` : ''}.`,
+        )
+        return
+      }
+    }
+    setState('saving')
+    await window.commitea.config.set(payload)
+    onConnected()
+  }
+
+  const field = (
+    label: string,
+    value: string,
+    set: (v: string) => void,
+    opts: { placeholder?: string; type?: string; hint?: string } = {},
+  ) => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 5 }}>
+      <Input
+        label={label}
+        value={value}
+        type={opts.type}
+        placeholder={opts.placeholder}
+        onChange={(e) => set(e.target.value)}
+      />
+      {opts.hint ? <span style={{ font: 'var(--text-caption)', color: 'var(--ink-3)' }}>{opts.hint}</span> : null}
+    </div>
+  )
+
+  return (
+    <div
+      style={{
+        height: '100vh',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        background: 'var(--surface-app)',
+        padding: 24,
+      }}
+    >
+      <Card style={{ width: 460, maxWidth: '100%' }}>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 10, marginBottom: 6 }}>
+          <img src={logoIcon} width="28" height="28" alt="" style={{ borderRadius: 7, display: 'block' }} />
+          <span style={{ font: '400 24px/1 var(--font-serif-display)', color: 'var(--ink-1)' }}>
+            Commi<span style={{ color: 'var(--accent-text)' }}>Tea</span>
+          </span>
+        </div>
+        <p style={{ font: 'var(--text-body)', color: 'var(--ink-2)', margin: '0 0 18px' }}>
+          Connect your Gitea. Your token is stored encrypted on this machine and never leaves it.
+        </p>
+
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+          {field('Gitea URL', baseUrl, setBaseUrl, { placeholder: 'https://gitea.example.com' })}
+          <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 }}>
+            {field('Owner', owner, setOwner, { placeholder: 'your-org' })}
+            {field('Repository', repo, setRepo, { placeholder: 'your-repo' })}
+          </div>
+          {field('Access token', token, setToken, {
+            type: 'password',
+            placeholder: existing?.hasToken ? '•••••••• (saved — leave blank to keep)' : 'gitea PAT · scopes: repo + issue',
+          })}
+          {field('Model URL', modelUrl, setModelUrl, {
+            placeholder: 'http://localhost:1234/v1',
+            hint: 'Optional — an OpenAI-compatible endpoint for Reginald. Leave blank to keep chat off.',
+          })}
+        </div>
+
+        {error ? (
+          <p style={{ font: 'var(--text-agent)', color: 'var(--danger)', margin: '12px 0 0' }}>{error}</p>
+        ) : null}
+
+        <div style={{ display: 'flex', gap: 10, marginTop: 18 }}>
+          <Button onClick={() => void connect()} disabled={!ready || state !== 'idle'}>
+            {state === 'testing' ? 'Checking…' : state === 'saving' ? 'Connecting…' : existing ? 'Save' : 'Connect'}
+          </Button>
+        </div>
+      </Card>
+    </div>
+  )
+}

apps/desktop/src/renderer/src/components/screens/settings-screen.tsx

@@ -1,9 +1,22 @@
 import React from 'react'
 
+import type { PublicConfig } from '../../global.js'
 import { Badge, Button, Card, Icon, IconButton, Input, Radio, Select, Switch, Tag } from '../ui/index.js'
 
 // Settings — gitea connection, sync, model roles, labels, rituals, appearance
-export function SettingsScreen({ dark, setDark }: { dark: boolean; setDark: (v: boolean) => void }) {
+export function SettingsScreen({
+  dark,
+  setDark,
+  connection,
+  onReconnect,
+  onDisconnect,
+}: {
+  dark: boolean
+  setDark: (v: boolean) => void
+  connection?: PublicConfig | null
+  onReconnect?: () => void
+  onDisconnect?: () => void
+}) {
   const [webhooks, setWebhooks] = React.useState(true)
   const [reconcile, setReconcile] = React.useState(true)
   const [poll, setPoll] = React.useState(true)
@@ -24,25 +37,35 @@ export function SettingsScreen({ dark, setDark }: { dark: boolean; setDark: (v:
       </header>
 
       <Card overline="Gitea" title="Connection">
-        <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
-          <Input label="Base URL" icon="link" mono defaultValue="https://gitea.stephenmann.io" />
-          <Input label="Access token" icon="keyboard" mono type="password" defaultValue="ct_9f2e81c4a7d6" hint="Scopes: repo, issue. Nothing more." />
-          <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
-            <span style={{ font: '600 13px/1.2 var(--font-sans)', color: 'var(--ink-1)' }}>Managed repos</span>
-            <Row style={{ padding: '8px 12px', background: 'var(--paper-0)', border: '1px solid var(--line-1)', borderRadius: 'var(--radius-2)' }}>
-              <Icon name="git-branch" size={14} style={{ color: 'var(--ink-3)' }} />
-              <span style={{ font: 'var(--text-data)', color: 'var(--ink-1)', flex: 1 }}>stephen/commitea</span>
-              <Badge tone="ok" dot>syncing</Badge>
-              <IconButton icon="x" label="Stop managing" size="sm" />
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+          {connection ? (
+            <>
+              <Row style={{ padding: '8px 12px', background: 'var(--paper-0)', border: '1px solid var(--line-1)', borderRadius: 'var(--radius-2)' }}>
+                <Icon name="git-branch" size={14} style={{ color: 'var(--ink-3)' }} />
+                <span style={{ font: 'var(--text-data)', color: 'var(--ink-1)', flex: 1 }}>{connection.owner}/{connection.repo}</span>
+                <Badge tone="ok" dot>connected</Badge>
+              </Row>
+              <Row style={{ font: 'var(--text-caption)', color: 'var(--ink-3)', gap: 6 }}>
+                <Icon name="link" size={12} />{connection.baseUrl}
+              </Row>
+              <Row style={{ font: 'var(--text-caption)', color: 'var(--ink-3)', gap: 6 }}>
+                <Icon name="layers" size={12} />sidecar: {connection.pmStateRepo ?? `${connection.repo}-pm-state`}
+              </Row>
+              <Row style={{ font: 'var(--text-caption)', color: 'var(--ink-3)', gap: 6 }}>
+                <Icon name="sparkles" size={12} />model: {connection.modelUrl ?? 'not set — chat off'}
+              </Row>
+              <Note>Your token is stored encrypted on this machine. Delete the sidecar and resync — no truth is lost.</Note>
+              <Row style={{ gap: 8, marginTop: 2 }}>
+                <Button variant="secondary" size="sm" icon="settings-2" onClick={onReconnect}>Reconfigure</Button>
+                <Button variant="ghost" size="sm" onClick={onDisconnect}>Disconnect</Button>
+              </Row>
+            </>
+          ) : (
+            <Row style={{ gap: 8 }}>
+              <Note>Not connected.</Note>
+              <Button variant="secondary" size="sm" onClick={onReconnect}>Connect</Button>
             </Row>
-            <Row style={{ padding: '8px 12px', background: 'var(--paper-0)', border: '1px solid var(--line-1)', borderRadius: 'var(--radius-2)' }}>
-              <Icon name="layers" size={14} style={{ color: 'var(--ink-3)' }} />
-              <span style={{ font: 'var(--text-data)', color: 'var(--ink-1)', flex: 1 }}>stephen/pm-state</span>
-              <Badge>sidecar</Badge>
-            </Row>
-            <Note>The sidecar holds machine-derived state only. Delete it and resync — no truth is lost.</Note>
-            <Button variant="secondary" size="sm" icon="plus" style={{ alignSelf: 'flex-start' }}>Add repo</Button>
-          </div>
+          )}
         </div>
       </Card>
 

apps/desktop/src/renderer/src/components/shell/app-shell.tsx

@@ -3,7 +3,9 @@ import React, { useEffect, useState } from 'react'
 import logoIcon from '../../design/assets/logo-icon.png'
 import type { IssueChange } from '@commitea/core'
 
+import type { PublicConfig } from '../../global.js'
 import type { IssueRef } from '../../data/fixtures.js'
+import { ConnectScreen } from '../screens/connect-screen.js'
 import {
   backlogCalibration,
   capacityWorkers,
@@ -97,6 +99,8 @@ export function AppShell() {
   const [issue, setIssue] = useState<IssueRef | null>(null)
   const [readIds, setReadIds] = useState<number[]>([])
   const [milestoneId, setMilestoneId] = useState<number | null>(null)
+  const [gate, setGate] = useState<'checking' | 'connect' | 'ready'>('checking')
+  const [pubConfig, setPubConfig] = useState<PublicConfig | null>(null)
   const [backlog, refetchBacklog] = useBacklog()
   const capacityMembers = useCapacity()
   const workers = capacityWorkers(capacityMembers)
@@ -132,6 +136,16 @@ export function AppShell() {
     document.documentElement.setAttribute('data-theme', dark ? 'dark' : 'light')
   }, [dark])
 
+  // Gate: e2e/demo → the shell (fixtures); configured → the shell (real data);
+  // otherwise → the connect screen (each teammate brings their own token).
+  useEffect(() => {
+    window.commitea.gitea
+      .status()
+      .then((s) => setGate(s.demo || s.configured ? 'ready' : 'connect'))
+      .catch(() => setGate('connect'))
+    window.commitea.config.get().then(setPubConfig).catch(() => {})
+  }, [])
+
   const openIssue = (ref: IssueRef) => {
     if (view !== 'issue') setPrevView(view)
     setIssue(ref)
@@ -250,7 +264,20 @@ export function AppShell() {
       case 'directives':
         return <DirectivesScreen />
       case 'settings':
-        return <SettingsScreen dark={dark} setDark={setDark} />
+        return (
+          <SettingsScreen
+            dark={dark}
+            setDark={setDark}
+            connection={pubConfig}
+            onReconnect={() => setGate('connect')}
+            onDisconnect={() => {
+              void window.commitea.config.clear().then(() => {
+                setPubConfig(null)
+                setGate('connect')
+              })
+            }}
+          />
+        )
       case 'issue':
         return issue ? (
           <IssueScreen
@@ -270,6 +297,23 @@ export function AppShell() {
     }
   }
 
+  // Connection gate (real onboarding) comes before everything else.
+  if (gate === 'checking') {
+    return <div style={{ height: '100vh', background: 'var(--surface-app)' }} />
+  }
+  if (gate === 'connect') {
+    return (
+      <ConnectScreen
+        existing={pubConfig}
+        onConnected={() => {
+          window.commitea.config.get().then(setPubConfig).catch(() => {})
+          setGate('ready')
+          refetchBacklog()
+        }}
+      />
+    )
+  }
+
   // First run is full-window — no rail, no chat panel
   if (view === 'firstrun') {
     return <OnboardingScreen onDone={(dest) => setView(dest)} />

apps/desktop/src/renderer/src/components/shell/chat-panel.tsx

@@ -62,7 +62,7 @@ export function ChatPanel({ onOpenDirectives, offline, onApplyChange }: ChatPane
         <Icon name="sparkles" size={16} style={{ color: offline ? 'var(--ink-3)' : 'var(--jade)' }} />
         <span style={{ font: 'var(--text-body-strong)', color: 'var(--ink-1)' }}>Reginald</span>
         <span style={{ font: '400 11px var(--font-mono)', color: 'var(--ink-3)', marginLeft: 'auto' }}>
-          {offline ? 'offline · queueing' : live ? `${modelLabel} · local` : 'demo · scripted'}
+          {offline ? 'offline · queueing' : live ? `${modelLabel} · local` : 'no model'}
         </span>
         <IconButton icon="history" label="Directive log" size="sm" onClick={onOpenDirectives} />
       </header>
@@ -161,8 +161,8 @@ export function ChatPanel({ onOpenDirectives, offline, onApplyChange }: ChatPane
                 send()
               }
             }}
-            placeholder={offline ? 'Writes wait for the connection…' : 'Tell me what to do…'}
-            disabled={offline}
+            placeholder={offline ? 'Writes wait for the connection…' : live ? 'Tell me what to do…' : 'Add a Model URL in Settings…'}
+            disabled={offline || !live}
             rows={1}
             style={{
               flex: 1,
@@ -180,15 +180,15 @@ export function ChatPanel({ onOpenDirectives, offline, onApplyChange }: ChatPane
             type="button"
             onClick={send}
             aria-label="Send"
-            disabled={offline}
+            disabled={offline || !live}
             style={{
               width: 30,
               height: 30,
               borderRadius: 'var(--radius-2)',
               border: 'none',
-              cursor: offline ? 'not-allowed' : 'pointer',
-              background: offline ? 'var(--paper-3)' : 'var(--accent)',
-              color: offline ? 'var(--ink-3)' : 'var(--ink-inverse)',
+              cursor: offline || !live ? 'not-allowed' : 'pointer',
+              background: offline || !live ? 'var(--paper-3)' : 'var(--accent)',
+              color: offline || !live ? 'var(--ink-3)' : 'var(--ink-inverse)',
               display: 'inline-flex',
               alignItems: 'center',
               justifyContent: 'center',

apps/desktop/src/renderer/src/global.d.ts

@@ -49,9 +49,37 @@ export type BootPayload =
   | { configured: true; cached: false }
   | ({ configured: true; cached: true } & Omit<SnapshotPayload, 'configured'>)
 
+/** The saved connection config (never includes the token). */
+export interface PublicConfig {
+  baseUrl: string
+  owner: string
+  repo: string
+  pmStateRepo?: string
+  modelUrl?: string
+  hasToken: boolean
+}
+
+/** What the onboarding/settings form submits. */
+export interface ConfigInput {
+  baseUrl: string
+  owner: string
+  repo: string
+  token: string
+  pmStateRepo?: string
+  modelUrl?: string
+}
+
+/** The config bridge for team onboarding. */
+export interface ConfigBridge {
+  get(): Promise<PublicConfig | null>
+  test(cfg: ConfigInput): Promise<{ ok: boolean; error?: string }>
+  set(cfg: ConfigInput): Promise<{ ok: boolean }>
+  clear(): Promise<{ ok: boolean }>
+}
+
 /** The gitea bridge exposed by the preload over IPC (main-process backed). */
 export interface GiteaBridge {
-  status(): Promise<{ configured: boolean; repo: string | null }>
+  status(): Promise<{ configured: boolean; repo: string | null; demo: boolean }>
   boot(): Promise<BootPayload>
   reconcile(): Promise<SnapshotPayload>
   getIssue(index: number): Promise<GiteaIssue | null>
@@ -96,6 +124,7 @@ declare global {
       gitea: GiteaBridge
       model: ModelBridge
       pmstate: PmStateBridge
+      config: ConfigBridge
     }
   }
 }

apps/desktop/src/renderer/src/lib/use-chat.ts

@@ -2,13 +2,18 @@ import { useCallback, useEffect, useRef, useState } from 'react'
 
 import type { ChangeProposal, ChatMessage as WireMessage, IssueChange } from '@commitea/core'
 
-import { CANNED_REPLY, CHAT, type ChatMessage } from '../data/fixtures.js'
+import { CHAT, type ChatMessage } from '../data/fixtures.js'
 
 const LIVE_GREETING: ChatMessage = {
   from: 'agent',
   text: 'Morning. Ask me anything about the project — I check the real board before I answer.',
 }
 
+const NO_MODEL: ChatMessage = {
+  from: 'agent',
+  text: "Reginald is off — I need a model. Add a Model URL in Settings and chat turns on.",
+}
+
 export interface ChatState {
   msgs: ChatMessage[]
   thinking: boolean
@@ -55,10 +60,14 @@ export function useChat(onApplyChange?: (change: IssueChange) => Promise<{ ok: b
     window.commitea.model
       .status()
       .then((s) => {
-        if (alive && s.configured) {
+        if (!alive) return
+        if (s.configured) {
           setLive(true)
           setModel(s.model)
           setSeed([LIVE_GREETING])
+        } else {
+          // no model → clean "off" state, not a scripted fixture reply
+          setSeed([NO_MODEL])
         }
       })
       .catch(() => {})
@@ -78,10 +87,8 @@ export function useChat(onApplyChange?: (change: IssueChange) => Promise<{ ok: b
       setProposals([])
 
       if (!live) {
-        window.setTimeout(() => {
-          setThinking(false)
-          setConvo((c) => [...c, { from: 'agent', text: CANNED_REPLY }])
-        }, 900)
+        // no model configured — nothing to send (composer is disabled anyway)
+        setThinking(false)
         return
       }