diff --git a/docs/poyraz-ui-ai-consumer-guide.md b/docs/poyraz-ui-ai-consumer-guide.md
new file mode 100644
index 0000000..3740ce7
--- /dev/null
+++ b/docs/poyraz-ui-ai-consumer-guide.md
@@ -0,0 +1,2723 @@
+# Poyraz UI — AI Consumer Guide
+
+Bu doküman, `poyraz-ui` paketini başka bir React/Next.js projesinde kullanmak isteyen bir geliştiricinin veya bir AI kod asistanının doğrudan okuyup doğru kararlar verebilmesi için hazırlanmıştır.
+
+Amaç: Bir projede UI geliştirirken AI’a bu dosyayı verip “poyraz-ui kullanarak bu ekranı oluştur” dediğinizde, AI’ın doğru import path’lerini, doğru componentleri, doğru variantları, doğru tema yaklaşımını ve doğru tasarım dilini uygulaması.
+
+Referans paket: `poyraz-ui@3.0.2`
+
+---
+
+## 1. AI için kısa talimat
+
+Eğer bu dokümanı bir AI’a vereceksen, aşağıdaki bölümü prompt’un başına koyabilirsin:
+
+```md
+Bu projede UI için poyraz-ui kullan.
+
+Kurallar:
+- React componentleri için `poyraz-ui/atoms`, `poyraz-ui/molecules`, `poyraz-ui/organisms` import path’lerini kullan.
+- Global CSS’e `@import "poyraz-ui/preset.css";` eklenmiş kabul et; ekli değilse ekle.
+- Gereksiz custom CSS yazma. Önce component variantlarını, radius/size/surface/appearance/effect prop’larını ve Tailwind utility classlarını kullan.
+- Tasarım dili: minimal, soft, hafif rounded, clean border, mümkün olduğunda gölgesiz, dark-mode uyumlu, semantic token bazlı.
+- Buttonlarda varsayılan hover motion için mümkünse `effect="swap"` kullan. Shine/fill/border-draw efektlerini yalnızca bilinçli vurgu için kullan.
+- Form, overlay, dropdown, dialog, sheet, tabs, tooltip gibi davranışlı componentlerde poyraz-ui molecule componentlerini kullan; kendi headless implementation’ını yazma.
+- Layout seviyesinde Navbar, Sidebar, Footer, AnnouncementBar ve DataTable gerekiyorsa `poyraz-ui/organisms` kullan.
+- Componentleri erişilebilir şekilde kur: label/input ilişkisi, keyboard navigation, focus ring, aria-label, dialog title gibi gereklilikleri koru.
+```
+
+---
+
+## 2. Poyraz UI nedir?
+
+Poyraz UI; React, Tailwind CSS v4 ve Radix UI temelli, minimal ve soft-glass tasarım diline sahip bir component sistemidir.
+
+Temel karakter:
+
+- Compact ve minimal görünüm
+- Clean border ağırlıklı yüzeyler
+- Gölge kullanımını minimumda tutan sade tasarım
+- Hafif rounded köşeler
+- Glass, soft, solid yüzey seçenekleri
+- Semantic token sistemi
+- Dark mode uyumu
+- Radix tabanlı erişilebilir primitives
+- Shadcn mantığına yakın source registry desteği
+- Npm paketi olarak merkezi kullanım
+- Atomic Design yapısı:
+  - Atoms
+  - Molecules
+  - Organisms
+  - Blocks/templates
+
+---
+
+## 3. Dağıtım modeli
+
+Poyraz UI iki farklı kullanım modelini destekler.
+
+### 3.1. Npm package kullanımı
+
+Merkezi versiyon yönetimi, hızlı kurulum ve paket importları için kullanılır.
+
+```bash
+pnpm add poyraz-ui@3
+```
+
+```tsx
+import { Button, Card, Input } from "poyraz-ui/atoms";
+import { Dialog, Tabs } from "poyraz-ui/molecules";
+import { Navbar } from "poyraz-ui/organisms";
+```
+
+Bu modelde component kaynak kodu projenize kopyalanmaz. Paket güncellendikçe componentler merkezi olarak güncellenir.
+
+### 3.2. Source registry kullanımı
+
+Shadcn tarzı “component’i projeye kopyala, sahiplen ve özelleştir” modeli için kullanılır.
+
+`components.json` içine registry namespace eklenir:
+
+```json
+{
+  "registries": {
+    "@poyraz": "https://ui.poyrazavsever.com/r/{name}.json"
+  }
+}
+```
+
+Örnek component ekleme:
+
+```bash
+pnpm dlx shadcn@latest add @poyraz/button
+```
+
+Bu yaklaşımda component, projenizin configured `aliases.ui` klasörüne kopyalanır. Çok derin özelleştirme gerekiyorsa bu model tercih edilir.
+
+AI’a tavsiye:
+
+- Proje hızlıca UI geliştirecekse npm package kullan.
+- Componentin kodu projede değiştirilecekse registry/source copy kullan.
+- Kullanıcı “shadcn gibi kopyalansın” derse source registry modelini öner.
+
+---
+
+## 4. Kurulum
+
+### 4.1. Paket kurulumu
+
+```bash
+pnpm add poyraz-ui@3
+```
+
+Alternatifler:
+
+```bash
+npm install poyraz-ui@3
+yarn add poyraz-ui@3
+```
+
+### 4.2. Peer dependencies
+
+Zorunlu:
+
+```json
+{
+  "react": ">=18",
+  "react-dom": ">=18",
+  "tailwindcss": ">=4"
+}
+```
+
+Opsiyonel:
+
+- `react-hook-form` — `Form` molecule için
+- `@hookform/resolvers` — schema resolver için
+- `zod` — form validation için
+- `reactive-switcher` — hazır theme objectleriyle dinamik tema için
+- `mermaid` — `Mermaid` molecule için
+
+### 4.3. CSS kurulumu
+
+Root global CSS dosyasına ekle:
+
+```css
+@import "tailwindcss";
+@import "poyraz-ui/preset.css";
+```
+
+Next.js App Router örneği:
+
+```tsx
+// app/layout.tsx
+import "./globals.css";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="tr">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+`poyraz-ui/preset.css` şunları sağlar:
+
+- Semantic color token bridge
+- Typography tokenları
+- Radius/token mapping
+- Motion keyframe ve animation utility’leri
+- Dark mode uyumlu CSS variable altyapısı
+- Componentlerin beklediği base CSS layer
+
+Bu import yoksa componentler görsel olarak eksik, renksiz veya animasyonsuz görünebilir.
+
+---
+
+## 5. Import stratejisi
+
+Önerilen import path’leri:
+
+```tsx
+import { Button, Card, Input } from "poyraz-ui/atoms";
+import { Dialog, DropdownMenu, Tabs } from "poyraz-ui/molecules";
+import { Navbar, Sidebar, Footer } from "poyraz-ui/organisms";
+```
+
+Ana barrel de kullanılabilir:
+
+```tsx
+import { Button, Dialog, Navbar } from "poyraz-ui";
+```
+
+Fakat AI için öneri:
+
+- Atom seviyesindeki componentleri `poyraz-ui/atoms` üzerinden import et.
+- Molecule seviyesindeki componentleri `poyraz-ui/molecules` üzerinden import et.
+- Layout ve büyük section componentlerini `poyraz-ui/organisms` üzerinden import et.
+- Theme objectleri gerekiyorsa `poyraz-ui/themes` kullan.
+
+Theme import:
+
+```tsx
+import { poyrazLightTheme, poyrazDarkTheme, poyrazThemes } from "poyraz-ui/themes";
+```
+
+Utility:
+
+```tsx
+import { cn } from "poyraz-ui";
+```
+
+---
+
+## 6. Tasarım dili
+
+Poyraz UI’ın ana tasarım dili:
+
+- Minimal
+- Soft
+- Hafif rounded
+- Clean border
+- Glassy ama abartısız
+- Gölgesiz veya çok düşük gölgeli
+- Semantic token bazlı
+- Form elemanlarında net focus ring
+- Overlaylerde kontrollü blur/surface
+- Dark mode’da kontrastı koruyan yüzeyler
+
+AI tasarım kararları:
+
+- Büyük gölgelerden kaçın.
+- Gereksiz custom border override yazma.
+- Kartlarda öncelikle `variant="default"`, `variant="glass"`, `variant="soft"` veya `variant="outline"` kullan.
+- Buttonlarda vurgu CTA için `variant="default"`; ikincil CTA için `variant="secondary"`, `variant="outline"` veya `variant="glass"` kullan.
+- Radius için genellikle `radius="sm"` veya `radius="md"` tercih et.
+- Çok pill/rounded istenmedikçe `radius="full"` kullanma.
+- Interactive hover için önce componentin kendi variant/effect prop’larını kullan.
+
+---
+
+## 7. Tema ve token sistemi
+
+Poyraz UI componentleri semantic Tailwind utility’leri ve CSS variable’ları üzerinden çalışır.
+
+Sık kullanılan semantic utility’ler:
+
+```txt
+bg-background
+bg-card
+bg-muted
+bg-primary
+text-foreground
+text-muted-foreground
+text-primary
+border-border
+ring-ring
+```
+
+Custom tema yapılacaksa genellikle global CSS’te `--poyraz-*` variable’ları override edilir.
+
+Örnek:
+
+```css
+:root {
+  --poyraz-primary: #dc2626;
+  --poyraz-radius-md: 0.625rem;
+}
+
+.dark {
+  --poyraz-background: #09090b;
+  --poyraz-foreground: #fafafa;
+}
+```
+
+AI için kural:
+
+- Hard-coded renkleri minimumda tut.
+- `#dc2626` gibi brand renkleri yalnızca gerçekten brand vurgusu gerekiyorsa kullan.
+- Önce `primary`, `muted`, `border`, `foreground`, `card` tokenlarını kullan.
+
+---
+
+## 8. Motion sistemi
+
+Poyraz UI motion sistemi CSS-only yaklaşımı tercih eder.
+
+Button effect’leri:
+
+```tsx
+<Button effect="none">Default</Button>
+<Button effect="shine">Shine</Button>
+<Button effect="fill" fillDirection="up">Fill</Button>
+<Button effect="swap" swapTarget="both">Swap</Button>
+<Button effect="border-draw">Border Draw</Button>
+```
+
+Button effect prop değerleri:
+
+```ts
+type ButtonEffect = "none" | "shine" | "fill" | "swap" | "border-draw";
+type ButtonFillDirection = "right" | "left" | "up" | "down";
+type ButtonSwapTarget = "icon" | "label" | "both";
+```
+
+AI için motion kuralı:
+
+- Standart CTA için `effect="swap"` kullan.
+- Shine efektini premium/brand vurgu için kullan.
+- Fill efektini güçlü hover dolum istenirse kullan.
+- Border-draw efektini outline butonlarda dekoratif vurgu için kullan.
+- Hareketleri erişilebilir tut; animasyonla bilgi verme.
+
+Swap anatomy için önerilen yapı:
+
+```tsx
+import { Button, ButtonIcon, ButtonLabel } from "poyraz-ui/atoms";
+
+<Button effect="swap" swapTarget="both">
+  <ButtonLabel>Devam et</ButtonLabel>
+  <ButtonIcon>
+    <ArrowRightIcon />
+  </ButtonIcon>
+</Button>
+```
+
+Not:
+
+- `asChild` kullanımı bazı durumlarda özel children yapılarıyla effect anatomy’sini bozabilir.
+- Swap effect’in net çalışması için `ButtonLabel` ve `ButtonIcon` doğrudan `Button` içinde kullanılmalıdır.
+
+---
+
+## 9. Atoms
+
+Atoms, en küçük ve temel UI yapı taşlarıdır.
+
+### 9.1. Button
+
+Import:
+
+```tsx
+import { Button, ButtonIcon, ButtonLabel } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Button>Kaydet</Button>
+
+<Button variant="secondary" size="sm" radius="sm">
+  İptal
+</Button>
+
+<Button effect="swap" swapTarget="both">
+  <ButtonLabel>Detayları gör</ButtonLabel>
+  <ButtonIcon>→</ButtonIcon>
+</Button>
+```
+
+Variantlar:
+
+```txt
+default
+secondary
+outline
+glass
+destructive
+soft
+ghost
+link
+```
+
+Size:
+
+```txt
+xs
+sm
+default
+lg
+icon-sm
+icon
+icon-lg
+```
+
+Radius:
+
+```txt
+none
+xs
+sm
+md
+lg
+xl
+2xl
+full
+```
+
+Effect:
+
+```txt
+none
+shine
+fill
+swap
+border-draw
+```
+
+AI önerisi:
+
+- Primary CTA: `variant="default" effect="swap"`
+- Secondary CTA: `variant="secondary" effect="swap"`
+- Icon-only: `size="icon"` ve mutlaka `aria-label`
+- Loading durumunda `loading` prop kullan.
+
+---
+
+### 9.2. Badge
+
+Import:
+
+```tsx
+import { Badge } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Badge>Yeni</Badge>
+<Badge variant="outline">Beta</Badge>
+<Badge variant="success">Aktif</Badge>
+```
+
+Variantlar:
+
+```txt
+default
+secondary
+outline
+glass
+info
+success
+warning
+destructive
+```
+
+Size:
+
+```txt
+sm
+default
+lg
+```
+
+Radius:
+
+```txt
+sm
+md
+full
+```
+
+AI önerisi:
+
+- Durum göstergelerinde `success`, `warning`, `destructive`, `info`
+- Kategori etiketlerinde `outline` veya `secondary`
+- Premium/soft yüzeylerde `glass`
+
+---
+
+### 9.3. Avatar
+
+Import:
+
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Avatar size="lg" radius="full">
+  <AvatarImage src="/avatar.png" alt="Poyraz Avsever" />
+  <AvatarFallback>PA</AvatarFallback>
+</Avatar>
+```
+
+Size:
+
+```txt
+xs
+sm
+default
+lg
+xl
+```
+
+Radius:
+
+```txt
+sm
+md
+lg
+full
+```
+
+AI önerisi:
+
+- Kullanıcı profilinde `radius="full"`
+- Kurumsal logo/avatar gridlerinde `radius="md"` veya `radius="lg"`
+
+---
+
+### 9.4. Card
+
+Import:
+
+```tsx
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+  CardAction,
+  CardImage,
+} from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Card variant="default" radius="md">
+  <CardHeader>
+    <CardTitle>Başlık</CardTitle>
+    <CardDescription>Açıklama metni</CardDescription>
+  </CardHeader>
+  <CardContent>
+    İçerik
+  </CardContent>
+  <CardFooter>
+    Footer
+  </CardFooter>
+</Card>
+```
+
+Variantlar:
+
+```txt
+default
+outline
+glass
+soft
+ghost
+elevated
+interactive
+bordered
+highlight
+```
+
+Radius:
+
+```txt
+none
+md
+lg
+xl
+2xl
+```
+
+AI önerisi:
+
+- Genel layout kartı: `variant="default"`
+- Cam efektli dashboard: `variant="glass"`
+- Subtle info yüzeyi: `variant="soft"`
+- Clickable kart: `variant="interactive"`
+- Gölge istenmiyorsa `elevated` kullanma.
+
+---
+
+### 9.5. Card variants
+
+Import:
+
+```tsx
+import {
+  BasicContentCard,
+  ImageContentCard,
+  HorizontalCard,
+  ProfileCard,
+  StatisticCard,
+  PricingPlanCard,
+  FeatureCard,
+  GlassCard,
+  InteractiveCard,
+  ExpandableCard,
+} from "poyraz-ui/atoms";
+```
+
+Kullanım amaçları:
+
+- `BasicContentCard`: başlık, açıklama, aksiyon butonu
+- `ImageContentCard`: üstte görsel, altta içerik
+- `HorizontalCard`: solda görsel, sağda içerik
+- `ProfileCard`: avatar, isim, rol, bio, sosyal aksiyonlar
+- `StatisticCard`: KPI/metrik kartı
+- `PricingPlanCard`: fiyat planı
+- `FeatureCard`: ikon + özellik başlığı + açıklama
+- `GlassCard`: glass yüzey kartı
+- `InteractiveCard`: hover/interaction odaklı kart
+- `ExpandableCard`: açılır/kapanır içerik kartı
+
+AI önerisi:
+
+- Landing page feature grid için `FeatureCard`
+- Dashboard KPI için `StatisticCard`
+- Pricing ekranı için `PricingPlanCard`
+- Portfolio kişi kartı için `ProfileCard`
+
+---
+
+### 9.6. Input
+
+Import:
+
+```tsx
+import { Input, InputGroup, InputGroupAddon } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Input placeholder="E-posta" />
+
+<InputGroup variant="glass" radius="md">
+  <InputGroupAddon position="start">@</InputGroupAddon>
+  <Input placeholder="kullanici" />
+</InputGroup>
+```
+
+Field variantları:
+
+```txt
+default
+glass
+soft
+```
+
+Radius:
+
+```txt
+none
+sm
+md
+lg
+xl
+full
+```
+
+AI önerisi:
+
+- Normal form alanı: `variant="default"`
+- Cam yüzeylerde: `variant="glass"`
+- Hafif arka planlı alanlarda: `variant="soft"`
+- Icon prefix/suffix için `InputGroup` + `InputGroupAddon`
+
+---
+
+### 9.7. Form Fields
+
+Import:
+
+```tsx
+import {
+  NumberInput,
+  MaskedInput,
+  SearchInput,
+  PhoneInput,
+  PasswordInput,
+  UrlInput,
+  applyInputMask,
+} from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<SearchInput placeholder="Ara..." onSearch={(value) => console.log(value)} />
+
+<PhoneInput
+  countryCode="+90"
+  mask="### ### ## ##"
+  onValueChange={(formatted, raw) => console.log(formatted, raw)}
+/>
+
+<UrlInput
+  protocol="https://"
+  onValueChange={(value, absoluteUrl) => console.log(absoluteUrl)}
+/>
+
+<PasswordInput placeholder="Şifre" />
+
+<MaskedInput
+  mask="##/##/####"
+  placeholder="gg/aa/yyyy"
+  onValueChange={(formatted, raw) => console.log(formatted, raw)}
+/>
+```
+
+AI önerisi:
+
+- Search box için custom input yazma; `SearchInput`
+- Telefon için `PhoneInput`
+- URL için `UrlInput`
+- Şifre için `PasswordInput`
+- Basit maskeler için `MaskedInput`
+
+---
+
+### 9.8. Textarea
+
+Import:
+
+```tsx
+import { Textarea } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Textarea variant="soft" radius="md" placeholder="Mesajınız" />
+```
+
+Variantlar `Input` ile aynıdır:
+
+```txt
+default
+glass
+soft
+```
+
+---
+
+### 9.9. Checkbox
+
+Import:
+
+```tsx
+import { Checkbox } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<div className="flex items-center gap-2">
+  <Checkbox id="terms" />
+  <Label htmlFor="terms">Şartları kabul ediyorum</Label>
+</div>
+```
+
+Radix tabanlıdır. Controlled veya uncontrolled kullanılabilir.
+
+---
+
+### 9.10. Radio Group
+
+Import:
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<RadioGroup defaultValue="monthly">
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="monthly" value="monthly" />
+    <Label htmlFor="monthly">Aylık</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="yearly" value="yearly" />
+    <Label htmlFor="yearly">Yıllık</Label>
+  </div>
+</RadioGroup>
+```
+
+---
+
+### 9.11. Switch
+
+Import:
+
+```tsx
+import { Switch } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Switch checked={enabled} onCheckedChange={setEnabled} />
+```
+
+AI önerisi:
+
+- Aç/kapat ayarlarında kullan.
+- Checkbox yerine boolean ayar toggle’larında tercih et.
+
+---
+
+### 9.12. Label
+
+Import:
+
+```tsx
+import { Label } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Label htmlFor="email">E-posta</Label>
+<Input id="email" type="email" />
+```
+
+AI kuralı:
+
+- Form alanlarına her zaman label ekle.
+- Placeholder label’ın yerine geçmez.
+
+---
+
+### 9.13. Separator
+
+Import:
+
+```tsx
+import { Separator } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Separator />
+<Separator orientation="vertical" />
+```
+
+---
+
+### 9.14. Skeleton
+
+Import:
+
+```tsx
+import { Skeleton } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Skeleton className="h-8 w-48" />
+<Skeleton className="h-32 rounded-md" />
+```
+
+AI önerisi:
+
+- Veri yüklenirken layout shift azaltmak için kullan.
+
+---
+
+### 9.15. Scroll Area
+
+Import:
+
+```tsx
+import { ScrollArea } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<ScrollArea maxHeight={320} orientation="vertical">
+  Uzun içerik
+</ScrollArea>
+```
+
+Props:
+
+```txt
+maxHeight?: string | number
+orientation?: "vertical" | "horizontal" | "both"
+scrollbarSize?: "sm" | "md" | "lg"
+```
+
+---
+
+### 9.16. Logo
+
+Import:
+
+```tsx
+import { Logo } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Logo src="/logo.png" alt="Brand" href="/" effect="shine-loop" radius="sm" />
+```
+
+Effect:
+
+```txt
+none
+shine
+shine-loop
+```
+
+AI önerisi:
+
+- Navbar’da avatar yerine logo gerekiyorsa `Logo` kullan.
+- Premium/brand hissi için `effect="shine-loop"` kullanılabilir.
+
+---
+
+### 9.17. Typography ve TextEffect
+
+Import:
+
+```tsx
+import { Typography, TextEffect } from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<Typography variant="h1" component="h1">
+  Modern <TextEffect effect="shimmer" tone="primary">UI sistemi</TextEffect>
+</Typography>
+
+<Typography variant="p" className="text-muted-foreground">
+  Açıklama metni
+</Typography>
+```
+
+Typography variantları:
+
+```txt
+display
+h1
+h2
+h3
+h4
+large
+lead
+p
+body
+small
+caption
+muted
+blockquote
+list
+```
+
+Font:
+
+```txt
+primary
+secondary
+inherit
+```
+
+TextEffect variantları:
+
+```txt
+none
+marker
+strike
+outline
+hand-drawn
+contrast
+shimmer
+gradient
+glow
+boxed
+```
+
+Tone:
+
+```txt
+primary
+neutral
+warning
+```
+
+AI önerisi:
+
+- Heading’lerde `Typography` kullan.
+- Vurgulu kelimelerde custom span/CSS yerine `TextEffect` kullan.
+- Shiny gradient text için `effect="shimmer"` veya `effect="gradient"`.
+- Elle çizilmiş underline hissi için `effect="hand-drawn"`.
+- Marker vurgusu için `effect="marker"`.
+- Hollow text için `effect="outline"`.
+
+---
+
+### 9.18. Background Patterns
+
+Import:
+
+```tsx
+import {
+  PatternDots,
+  PatternGrid,
+  PatternLines,
+  PatternDiagonal,
+  PatternCross,
+  PatternCheckerboard,
+  PatternDiamond,
+  PatternZigzag,
+  PatternDashedGrid,
+  PatternRadial,
+} from "poyraz-ui/atoms";
+```
+
+Kullanım:
+
+```tsx
+<div className="relative overflow-hidden">
+  <PatternDots overlay opacity={0.12} size={24} />
+  <div className="relative z-10">İçerik</div>
+</div>
+```
+
+Pattern props:
+
+```txt
+color?: string
+opacity?: number
+size?: number
+overlay?: boolean
+```
+
+`PatternRadial` props:
+
+```txt
+from?: string
+to?: string
+opacity?: number
+overlay?: boolean
+```
+
+AI önerisi:
+
+- Hero background veya empty state için kullan.
+- Pattern overlay ise parent `relative overflow-hidden` olmalı.
+
+---
+
+## 10. Molecules
+
+Molecules, birkaç atomun birlikte oluşturduğu daha davranışlı UI parçalarıdır.
+
+### 10.1. Accordion
+
+Import:
+
+```tsx
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Accordion type="single" collapsible>
+  <AccordionItem value="item-1" separated surface="soft" radius="md">
+    <AccordionTrigger>Başlık</AccordionTrigger>
+    <AccordionContent>İçerik</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+AI önerisi:
+
+- FAQ, settings, detay aç/kapa için kullan.
+- Custom collapse state yazma; Radix props kullan.
+
+---
+
+### 10.2. Alert
+
+Import:
+
+```tsx
+import { Alert, AlertTitle, AlertDescription } from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Alert variant="success" appearance="soft" radius="md" motion="slide">
+  <AlertTitle>Başarılı</AlertTitle>
+  <AlertDescription>Kayıt tamamlandı.</AlertDescription>
+</Alert>
+```
+
+Variant:
+
+```txt
+default
+info
+success
+warning
+destructive
+```
+
+Appearance:
+
+```txt
+inline
+outline
+glass
+soft
+filled
+```
+
+Motion:
+
+```txt
+none
+scale
+fade
+slide
+```
+
+Ek props:
+
+```txt
+icon?: ReactNode
+dismissible?: boolean
+onDismiss?: () => void
+dismissLabel?: string
+```
+
+AI önerisi:
+
+- Inline bilgilendirme: `appearance="inline"`
+- Form/global feedback: `appearance="soft"` veya `appearance="outline"`
+- Kritik hata: `variant="destructive"`
+
+---
+
+### 10.3. Tooltip
+
+Import:
+
+```tsx
+import {
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+  TooltipProvider,
+} from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button size="icon" aria-label="Ayarlar">⚙</Button>
+    </TooltipTrigger>
+    <TooltipContent side="bottom" surface="soft" radius="sm">
+      Ayarlar
+    </TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+Surface:
+
+```txt
+solid
+soft
+glass
+```
+
+Radius:
+
+```txt
+none
+sm
+md
+lg
+xl
+```
+
+AI önerisi:
+
+- Icon-only butonlarda tooltip kullan.
+- Tooltip içeriğini kısa tut.
+
+---
+
+### 10.4. Popover
+
+Import:
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent } from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button>Filtre</Button>
+  </PopoverTrigger>
+  <PopoverContent surface="soft" radius="md" align="end">
+    Filtre içeriği
+  </PopoverContent>
+</Popover>
+```
+
+AI önerisi:
+
+- Küçük floating panel için Popover.
+- Büyük panel gerekiyorsa Sheet veya Dialog.
+
+---
+
+### 10.5. Hover Card
+
+Import:
+
+```tsx
+import { HoverCard, HoverCardTrigger, HoverCardContent } from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <a href="/profile">Poyraz</a>
+  </HoverCardTrigger>
+  <HoverCardContent surface="glass" radius="md">
+    Profil özeti
+  </HoverCardContent>
+</HoverCard>
+```
+
+AI önerisi:
+
+- Profil preview, link preview, mini context kartları için kullan.
+
+---
+
+### 10.6. Dropdown Menu
+
+Import:
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuShortcut,
+} from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="outline">Menü</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end" surface="solid" radius="md">
+    <DropdownMenuLabel>Hesap</DropdownMenuLabel>
+    <DropdownMenuItem interactiveMotion="shift">Profil</DropdownMenuItem>
+    <DropdownMenuItem>Ayarlar</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Çıkış</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+AI önerisi:
+
+- Click menu için DropdownMenu.
+- Hover-only mega menu gerekiyorsa Navbar organism altındaki menu parçalarını düşün.
+- Social dropdown gibi sade menülerde `surface="solid"` kullan.
+
+---
+
+### 10.7. Select
+
+Import:
+
+```tsx
+import {
+  Select,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectGroup,
+  SelectLabel,
+  SelectItem,
+  SelectSeparator,
+} from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Select defaultValue="tr">
+  <SelectTrigger>
+    <SelectValue placeholder="Dil seç" />
+  </SelectTrigger>
+  <SelectContent surface="soft" radius="md">
+    <SelectGroup>
+      <SelectLabel>Diller</SelectLabel>
+      <SelectItem value="tr">Türkçe</SelectItem>
+      <SelectItem value="en">English</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+AI önerisi:
+
+- Native select yerine bu componenti kullan.
+- Form içinde `FormField` ile birlikte kullanılabilir.
+
+---
+
+### 10.8. Dialog
+
+Import:
+
+```tsx
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+  DialogClose,
+} from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Dialog aç</Button>
+  </DialogTrigger>
+  <DialogContent surface="solid" radius="lg">
+    <DialogHeader>
+      <DialogTitle>Başlık</DialogTitle>
+      <DialogDescription>Açıklama</DialogDescription>
+    </DialogHeader>
+    İçerik
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button variant="secondary">Kapat</Button>
+      </DialogClose>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+AI önerisi:
+
+- Kritik confirmation veya küçük modal akışlarında Dialog.
+- Her Dialog içinde görünür veya `sr-only` title bulundur.
+
+---
+
+### 10.9. Modal
+
+Import:
+
+```tsx
+import {
+  Modal,
+  ModalTrigger,
+  ModalContent,
+  ModalHeader,
+  ModalTitle,
+  ModalDescription,
+  ModalFooter,
+  ModalClose,
+} from "poyraz-ui/molecules";
+```
+
+Modal, Dialog’a benzer fakat Poyraz UI’ın daha opinionated modal surface/size yaklaşımını sunar.
+
+AI önerisi:
+
+- Uygulama içi custom modal tasarımları için Modal.
+- Radix-like standart kullanım için Dialog.
+
+---
+
+### 10.10. Sheet
+
+Import:
+
+```tsx
+import {
+  Sheet,
+  SheetTrigger,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetDescription,
+  SheetFooter,
+  SheetClose,
+} from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button>Detaylar</Button>
+  </SheetTrigger>
+  <SheetContent side="right" surface="solid" radius="md">
+    <SheetHeader>
+      <SheetTitle>Detaylar</SheetTitle>
+      <SheetDescription>Ek bilgiler</SheetDescription>
+    </SheetHeader>
+  </SheetContent>
+</Sheet>
+```
+
+AI önerisi:
+
+- Sağdan açılan ayar, filtre, detay paneli için Sheet.
+- Mobilde full-screen hissi gereken yan paneller için uygun.
+
+---
+
+### 10.11. Drawer
+
+Import:
+
+```tsx
+import {
+  Drawer,
+  DrawerTrigger,
+  DrawerContent,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerDescription,
+  DrawerFooter,
+  DrawerClose,
+} from "poyraz-ui/molecules";
+```
+
+Drawer `vaul` tabanlıdır.
+
+AI önerisi:
+
+- Mobil bottom sheet davranışı için Drawer.
+- Desktop side panel için Sheet tercih et.
+
+---
+
+### 10.12. Command Palette
+
+Import:
+
+```tsx
+import {
+  CommandPalette,
+  CommandPaletteTrigger,
+  CommandPaletteContent,
+  CommandPaletteInput,
+  CommandPaletteList,
+  CommandPaletteGroup,
+  CommandPaletteItem,
+  CommandPaletteEmpty,
+  CommandPaletteSeparator,
+  CommandPaletteFooter,
+  useCommandPalette,
+} from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<CommandPalette>
+  <CommandPaletteTrigger asChild>
+    <Button variant="outline">Ara</Button>
+  </CommandPaletteTrigger>
+  <CommandPaletteContent>
+    <CommandPaletteInput placeholder="Komut ara..." />
+    <CommandPaletteList>
+      <CommandPaletteEmpty>Sonuç yok.</CommandPaletteEmpty>
+      <CommandPaletteGroup heading="Sayfalar">
+        <CommandPaletteItem value="dashboard">Dashboard</CommandPaletteItem>
+        <CommandPaletteItem value="settings">Ayarlar</CommandPaletteItem>
+      </CommandPaletteGroup>
+    </CommandPaletteList>
+    <CommandPaletteFooter>⌘K ile aç</CommandPaletteFooter>
+  </CommandPaletteContent>
+</CommandPalette>
+```
+
+AI önerisi:
+
+- Global search/command menu için kullan.
+- Navbar search butonuna bağlanabilir.
+
+---
+
+### 10.13. Tabs
+
+Import:
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Tabs defaultValue="overview">
+  <TabsList>
+    <TabsTrigger value="overview">Genel</TabsTrigger>
+    <TabsTrigger value="settings">Ayarlar</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview">Genel içerik</TabsContent>
+  <TabsContent value="settings">Ayarlar içeriği</TabsContent>
+</Tabs>
+```
+
+AI önerisi:
+
+- Nav link görünümü için de Tabs yapısı kullanılabilir.
+- Sayfa içi section switching için uygundur.
+
+---
+
+### 10.14. Breadcrumb
+
+Import:
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+} from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Ana sayfa</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Projeler</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+---
+
+### 10.15. Pagination
+
+Import:
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
+} from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="?page=1" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="?page=2" isActive>2</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationEllipsis />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="?page=3" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+---
+
+### 10.16. Sonner / Toaster
+
+Import:
+
+```tsx
+import { Toaster, toast } from "poyraz-ui/molecules";
+```
+
+Root layout:
+
+```tsx
+<body>
+  {children}
+  <Toaster />
+</body>
+```
+
+Toast:
+
+```tsx
+toast.success("Kaydedildi");
+toast.error("Bir hata oluştu");
+toast.promise(save(), {
+  loading: "Kaydediliyor...",
+  success: "Kaydedildi",
+  error: "Kaydedilemedi",
+});
+```
+
+AI önerisi:
+
+- Form submit sonrası global feedback için toast kullan.
+- Inline hata için Alert/FormMessage kullan.
+
+---
+
+### 10.17. Form
+
+Import:
+
+```tsx
+import {
+  Form,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormDescription,
+  FormMessage,
+} from "poyraz-ui/molecules";
+```
+
+`react-hook-form` ile kullanılır.
+
+Kullanım:
+
+```tsx
+<Form {...form}>
+  <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+    <FormField
+      control={form.control}
+      name="email"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>E-posta</FormLabel>
+          <FormControl>
+            <Input type="email" placeholder="poyraz@example.com" {...field} />
+          </FormControl>
+          <FormDescription>İş e-postanı kullan.</FormDescription>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+    <Button type="submit">Gönder</Button>
+  </form>
+</Form>
+```
+
+AI önerisi:
+
+- Validasyonlu formlarda bu yapı dışına çıkma.
+- `FormMessage` kullanarak hata mesajlarını erişilebilir yap.
+
+---
+
+### 10.18. Calendar
+
+Import:
+
+```tsx
+import { Calendar } from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Calendar mode="single" selected={date} onSelect={setDate} />
+```
+
+Mode:
+
+```txt
+single
+range
+```
+
+AI önerisi:
+
+- Inline takvim için Calendar.
+- Input ile açılan tarih seçimi için DatePicker.
+
+---
+
+### 10.19. Date Picker
+
+Import:
+
+```tsx
+import { DatePicker } from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<DatePicker value={date} onChange={setDate} placeholder="Tarih seç" />
+```
+
+AI önerisi:
+
+- Form tarih alanı için DatePicker kullan.
+
+---
+
+### 10.20. Autocomplete
+
+Import:
+
+```tsx
+import { Autocomplete } from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Autocomplete
+  options={[
+    { value: "react", label: "React" },
+    { value: "next", label: "Next.js", description: "React framework" },
+  ]}
+  placeholder="Teknoloji ara..."
+/>
+```
+
+AI önerisi:
+
+- Select gibi ama arama/filter gerekiyorsa Autocomplete.
+
+---
+
+### 10.21. Mermaid
+
+Import:
+
+```tsx
+import { Mermaid } from "poyraz-ui/molecules";
+```
+
+Kullanım:
+
+```tsx
+<Mermaid
+  chart={`graph TD
+    A[Start] --> B[Build]
+    B --> C[Ship]
+  `}
+/>
+```
+
+Not:
+
+- `mermaid` peer dependency gerektirir.
+
+---
+
+### 10.22. Card Templates
+
+Import:
+
+```tsx
+import {
+  ArticleCard,
+  ImageCard,
+  NewsCard,
+  StatsCard,
+  TestimonialCard,
+  PricingCard,
+  ProductCard,
+  StarRating,
+} from "poyraz-ui/molecules";
+```
+
+#### ArticleCard
+
+Blog/article kartları için:
+
+```tsx
+<ArticleCard
+  title="Building with Poyraz UI"
+  description="Soft glass component sistemi."
+  image="/cover.png"
+  category="Design"
+  href="/blog/poyraz-ui"
+/>
+```
+
+#### ImageCard
+
+Görsel ağırlıklı proje/portfolio kartları için:
+
+```tsx
+<ImageCard
+  image="/project.png"
+  title="Project Name"
+  description="Kısa açıklama"
+  badge="Web App"
+  href="/projects/project-name"
+/>
+```
+
+#### NewsCard
+
+Yatay haber/post listeleri için:
+
+```tsx
+<NewsCard
+  image="/post.png"
+  title="Yeni yazı"
+  category="Blog"
+  date="2026-07-16"
+  href="/blog/new-post"
+/>
+```
+
+#### StatsCard
+
+Dashboard metrikleri için:
+
+```tsx
+<StatsCard
+  label="Aktif kullanıcı"
+  value="24.6K"
+  trend="up"
+  trendValue="+12%"
+/>
+```
+
+#### TestimonialCard
+
+Referans/yorum kartı:
+
+```tsx
+<TestimonialCard
+  quote="Harika çalıştı."
+  author="Ada Raimova"
+  role="Founder"
+  avatar="/ada.png"
+  rating={5}
+/>
+```
+
+#### PricingCard
+
+Fiyatlandırma:
+
+```tsx
+<PricingCard
+  title="Pro"
+  price="$19"
+  period="/mo"
+  features={["10 Projects", "Priority Support"]}
+  action={<Button>Choose Plan</Button>}
+/>
+```
+
+#### ProductCard
+
+E-commerce ürün kartı:
+
+```tsx
+<ProductCard
+  title="Headphones"
+  price="$99"
+  image="/headphone.png"
+  rating={4.8}
+/>
+```
+
+#### StarRating
+
+Yıldız rating:
+
+```tsx
+<StarRating rating={4.5} />
+```
+
+AI önerisi:
+
+- Blog için `ArticleCard` veya `NewsCard`
+- Projeler için `ImageCard`
+- Dashboard KPI için `StatsCard`
+- Referanslar için `TestimonialCard`
+- Pricing sayfası için `PricingCard`
+- Ürün gridleri için `ProductCard`
+
+---
+
+## 11. Organisms
+
+Organisms, kompleks layout ve app shell parçalarıdır.
+
+### 11.1. Navbar
+
+Import:
+
+```tsx
+import {
+  Navbar,
+  NavbarTopBar,
+  NavbarTopBarSection,
+  NavbarMain,
+  NavbarBrand,
+  NavbarLinks,
+  NavbarLink,
+  NavbarDropdown,
+  NavbarDropdownTrigger,
+  NavbarMegaMenu,
+  NavbarMegaMenuLinks,
+  NavbarMegaMenuFeatured,
+  NavbarMegaMenuItem,
+  NavbarPopoverDropdown,
+  NavbarPopoverDropdownItem,
+  NavbarPanelDropdown,
+  NavbarPanelDropdownItem,
+  NavbarActions,
+  NavbarMobileToggle,
+  NavbarMobileMenu,
+  NavbarMobileLink,
+  NavbarMobileGroup,
+  NavbarMobileActions,
+  NavbarMobileDropdown,
+  NavbarMobileDrillMenu,
+  NavbarMobileDrillTrigger,
+  NavbarMobileDrillPanel,
+  NavbarSearch,
+  NavbarDivider,
+} from "poyraz-ui/organisms";
+```
+
+Basit kullanım:
+
+```tsx
+<Navbar variant="default">
+  <NavbarMain>
+    <NavbarBrand href="/" logo={<img src="/logo.png" alt="" />}>
+      App
+    </NavbarBrand>
+    <NavbarLinks>
+      <NavbarLink href="/docs">Docs</NavbarLink>
+      <NavbarLink href="/components">Components</NavbarLink>
+    </NavbarLinks>
+    <NavbarActions>
+      <NavbarSearch placeholder="Ara..." />
+      <Button>Başla</Button>
+    </NavbarActions>
+  </NavbarMain>
+</Navbar>
+```
+
+AI önerisi:
+
+- Ana site navbarı için Navbar organism kullan.
+- Logo için mümkünse `Logo` atom veya `NavbarBrand` kullan.
+- Linkler solda, actionlar sağda olacaksa `NavbarMain` içinde `NavbarBrand` + `NavbarLinks` + `NavbarActions`.
+- Mobil menü gerekiyorsa `NavbarMobileToggle` + `NavbarMobileMenu`.
+- Global search gerekiyorsa `NavbarSearch` veya `CommandPalette` ile birlikte kullan.
+
+---
+
+### 11.2. Sidebar
+
+Import:
+
+```tsx
+import {
+  Sidebar,
+  SidebarProvider,
+  SidebarPanel,
+  SidebarHeader,
+  SidebarBranding,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarSection,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuAction,
+  SidebarSeparator,
+  SidebarBadge,
+  SidebarFooter,
+  SidebarTrigger,
+  SidebarRail,
+  SidebarSearch,
+  SidebarSubMenu,
+  SidebarSubMenuItem,
+  SidebarUserProfile,
+} from "poyraz-ui/organisms";
+```
+
+Kullanım:
+
+```tsx
+<SidebarProvider variant="collapsible">
+  <Sidebar variant="collapsible">
+    <SidebarPanel>
+      <SidebarHeader>
+        <SidebarBranding title="Dashboard" subtitle="Admin" />
+      </SidebarHeader>
+      <SidebarContent>
+        <SidebarMenu>
+          <SidebarMenuItem active href="/dashboard" icon={<HomeIcon />}>
+            Dashboard
+          </SidebarMenuItem>
+          <SidebarMenuItem href="/settings" icon={<SettingsIcon />}>
+            Settings
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarContent>
+      <SidebarFooter>
+        <SidebarUserProfile name="Poyraz" role="Developer" initials="PA" />
+      </SidebarFooter>
+    </SidebarPanel>
+  </Sidebar>
+</SidebarProvider>
+```
+
+Sidebar variantları:
+
+```txt
+default
+collapsible
+floating
+mini
+dark
+bordered
+inset
+```
+
+AI önerisi:
+
+- Dashboard layoutlarında SidebarProvider kullan.
+- Collapsible sidebar için `variant="collapsible"`.
+- Compact icon sidebar için `variant="mini"`.
+- Mobile drawer ihtiyacı için Sidebar mobile state veya Sheet ile kombinasyon.
+
+---
+
+### 11.3. Footer
+
+Import:
+
+```tsx
+import {
+  Footer,
+  FooterGrid,
+  FooterSection,
+  FooterHeading,
+  FooterLink,
+  FooterBrand,
+  FooterSocials,
+  FooterSocialLink,
+  FooterDivider,
+  FooterBottom,
+  FooterBottomLinks,
+  FooterDescription,
+  FooterBadge,
+  FooterLinkGroup,
+  FooterCTA,
+  FooterApp,
+  FooterAppLink,
+  FooterNewsletter,
+} from "poyraz-ui/organisms";
+```
+
+Kullanım:
+
+```tsx
+<Footer variant="minimal">
+  <FooterGrid>
+    <FooterBrand>
+      <FooterHeading>Poyraz UI</FooterHeading>
+      <FooterDescription>Soft glass component system.</FooterDescription>
+    </FooterBrand>
+    <FooterSection>
+      <FooterHeading>Links</FooterHeading>
+      <FooterLink href="/docs">Docs</FooterLink>
+      <FooterLink href="/components">Components</FooterLink>
+    </FooterSection>
+  </FooterGrid>
+  <FooterDivider />
+  <FooterBottom>
+    <span>© 2026</span>
+    <FooterBottomLinks>
+      <FooterLink href="/privacy">Privacy</FooterLink>
+    </FooterBottomLinks>
+  </FooterBottom>
+</Footer>
+```
+
+Footer variantları:
+
+```txt
+minimal
+compact
+full
+branded
+centered
+dark
+```
+
+AI önerisi:
+
+- Landing page footer: `variant="minimal"` veya `variant="branded"`
+- App footer: `variant="compact"`
+- Koyu section footer: `variant="dark"`
+
+---
+
+### 11.4. Announcement Bar
+
+Import:
+
+```tsx
+import { AnnouncementBar } from "poyraz-ui/organisms";
+```
+
+Kullanım:
+
+```tsx
+<AnnouncementBar
+  variant="branded"
+  dismissible
+  icon={<SparklesIcon />}
+  action={<Button size="sm">İncele</Button>}
+>
+  Yeni sürüm yayında!
+</AnnouncementBar>
+```
+
+Variantlar:
+
+```txt
+default
+info
+success
+warning
+branded
+danger
+```
+
+AI önerisi:
+
+- Site-wide duyuru için kullan.
+- Dismiss state gerekiyorsa caller state yönetmeli veya kendi persistence hook’unu kullanmalı.
+
+---
+
+### 11.5. Data Table
+
+Import:
+
+```tsx
+import { DataTable, DataTableCore, type DataTableColumnDef } from "poyraz-ui/organisms";
+```
+
+Kullanım:
+
+```tsx
+type User = {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+};
+
+const columns: DataTableColumnDef<User>[] = [
+  { id: "name", header: "Name", accessorKey: "name", sortable: true },
+  { id: "email", header: "Email", accessorKey: "email" },
+  { id: "role", header: "Role", accessorKey: "role", filterable: true },
+];
+
+<DataTable
+  columns={columns}
+  data={users}
+  getRowId={(row) => row.id}
+  searchable
+  selectable
+  columnToggle
+  pageSize={10}
+  surface="solid"
+  radius="md"
+/>
+```
+
+DataTable props özeti:
+
+```txt
+columns
+data
+getRowId
+pageSize
+pagination
+searchable
+searchPlaceholder
+selectable
+onSelectionChange
+columnToggle
+className
+caption
+emptyMessage
+loading
+error
+stickyHeader
+tableMaxHeight
+density
+surface
+radius
+toolbar
+```
+
+Density:
+
+```txt
+compact
+default
+spacious
+```
+
+Surface:
+
+```txt
+solid
+soft
+glass
+```
+
+AI önerisi:
+
+- Basit tablo için DataTable.
+- Kendi pagination/search/sort yazma.
+- Daha kontrollü state gerekiyorsa DataTableCore kullan.
+
+---
+
+## 12. Blocks ve hazır template mantığı
+
+Registry içinde ayrıca block/template yapıları bulunur. Bunlar npm export’larından ziyade source registry üzerinden projeye kopyalanması hedeflenen daha büyük UI parçalarıdır.
+
+Blocks:
+
+- `article-card`
+- `image-card`
+- `news-card`
+- `stats-card`
+- `testimonial-card`
+- `pricing-card`
+- `product-card`
+- `navigation-block`
+- `mobile-navigation-block`
+- `mega-menu-block`
+- `mobile-sidebar-block`
+- `footer-blocks`
+- `dashboard-shell-block`
+- `glass-app-shell-block`
+- `auth-card-block`
+- `pricing-block`
+- `brand-hero-block`
+- `smart-dashboard-block`
+
+AI önerisi:
+
+- Kullanıcı “tam section tasarla” derse block mantığını öner.
+- Kullanıcı npm package ile ilerliyorsa molecule/organism componentleriyle aynı section’ı elle oluştur.
+- Kullanıcı “source-owned olsun” derse shadcn registry komutuyla block eklemeyi öner.
+
+Örnek:
+
+```bash
+pnpm dlx shadcn@latest add @poyraz/brand-hero-block
+pnpm dlx shadcn@latest add @poyraz/dashboard-shell-block
+```
+
+---
+
+## 13. Sık kullanılan layout reçeteleri
+
+### 13.1. Landing hero
+
+```tsx
+import { Button, ButtonIcon, ButtonLabel, Card, TextEffect, Typography } from "poyraz-ui/atoms";
+
+export function Hero() {
+  return (
+    <section className="mx-auto grid max-w-6xl gap-8 px-6 py-16 lg:grid-cols-[1fr_420px]">
+      <div className="flex flex-col justify-center gap-5">
+        <Typography variant="display" component="h1">
+          Modern <TextEffect effect="shimmer">soft UI</TextEffect> sistemi
+        </Typography>
+        <Typography variant="lead" className="text-muted-foreground">
+          React projeleri için minimal, token bazlı ve erişilebilir componentler.
+        </Typography>
+        <div className="flex gap-3">
+          <Button effect="swap" swapTarget="both">
+            <ButtonLabel>Başla</ButtonLabel>
+            <ButtonIcon>→</ButtonIcon>
+          </Button>
+          <Button variant="secondary" effect="swap" swapTarget="both">
+            <ButtonLabel>Docs</ButtonLabel>
+            <ButtonIcon>↗</ButtonIcon>
+          </Button>
+        </div>
+      </div>
+
+      <Card variant="glass" radius="xl" className="p-6">
+        Preview
+      </Card>
+    </section>
+  );
+}
+```
+
+### 13.2. Dashboard card grid
+
+```tsx
+import { StatsCard } from "poyraz-ui/molecules";
+
+<div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
+  <StatsCard label="Revenue" value="$56,000" trend="up" trendValue="+12.5%" />
+  <StatsCard label="Users" value="24,680" trend="up" trendValue="+8.2%" />
+  <StatsCard label="Errors" value="12" trend="down" trendValue="-2.1%" />
+  <StatsCard label="Conversion" value="3.46%" trend="neutral" />
+</div>
+```
+
+### 13.3. Settings form
+
+```tsx
+import { Button, Input, Switch, Label } from "poyraz-ui/atoms";
+import { Card, CardContent, CardHeader, CardTitle } from "poyraz-ui/atoms";
+
+<Card>
+  <CardHeader>
+    <CardTitle>Profil</CardTitle>
+  </CardHeader>
+  <CardContent className="space-y-4">
+    <div className="space-y-2">
+      <Label htmlFor="name">Ad</Label>
+      <Input id="name" placeholder="Adınız" />
+    </div>
+    <div className="flex items-center justify-between">
+      <Label htmlFor="notifications">Bildirimler</Label>
+      <Switch id="notifications" />
+    </div>
+    <Button effect="swap">Kaydet</Button>
+  </CardContent>
+</Card>
+```
+
+### 13.4. Global search with Command Palette
+
+```tsx
+import {
+  CommandPalette,
+  CommandPaletteTrigger,
+  CommandPaletteContent,
+  CommandPaletteInput,
+  CommandPaletteList,
+  CommandPaletteGroup,
+  CommandPaletteItem,
+  CommandPaletteEmpty,
+} from "poyraz-ui/molecules";
+import { Button } from "poyraz-ui/atoms";
+
+<CommandPalette>
+  <CommandPaletteTrigger asChild>
+    <Button variant="outline">Search</Button>
+  </CommandPaletteTrigger>
+  <CommandPaletteContent>
+    <CommandPaletteInput placeholder="Search docs..." />
+    <CommandPaletteList>
+      <CommandPaletteEmpty>No results.</CommandPaletteEmpty>
+      <CommandPaletteGroup heading="Pages">
+        <CommandPaletteItem value="docs">Docs</CommandPaletteItem>
+        <CommandPaletteItem value="components">Components</CommandPaletteItem>
+      </CommandPaletteGroup>
+    </CommandPaletteList>
+  </CommandPaletteContent>
+</CommandPalette>
+```
+
+---
+
+## 14. Erişilebilirlik kuralları
+
+AI şu kurallara uymalı:
+
+- Icon-only buttonlarda `aria-label` ekle.
+- Dialog/Sheet/Modal içinde mutlaka `Title` kullan.
+- Form inputlarında `Label` kullan.
+- Placeholder’ı label yerine kullanma.
+- Toast ile kritik bilgiyi tek başına verme; gerekiyorsa inline feedback de göster.
+- Focus ring’i custom classlarla silme.
+- Dropdown/Select/Tabs gibi davranışlı elementlerde Radix tabanlı poyraz-ui componentlerini kullan.
+- Keyboard navigation’ı bozacak wrapper yapıları kurma.
+- Disabled/loading state’leri prop üzerinden ver.
+
+---
+
+## 15. AI için component seçme rehberi
+
+Kullanıcı şunu isterse:
+
+| İstek | Kullanılacak component |
+| --- | --- |
+| Birincil aksiyon | `Button variant="default"` |
+| İkincil aksiyon | `Button variant="secondary"` veya `outline` |
+| Icon button | `Button size="icon"` |
+| Sayfa başlığı | `Typography variant="h1"` veya `h2` |
+| Vurgulu kelime | `TextEffect` |
+| Form input | `Input`, `Textarea`, `Form` |
+| Telefon/URL/şifre | `PhoneInput`, `UrlInput`, `PasswordInput` |
+| Küçük durum etiketi | `Badge` |
+| İçerik yüzeyi | `Card` |
+| Glass panel | `Card variant="glass"` veya `GlassCard` |
+| Dropdown aksiyon menüsü | `DropdownMenu` |
+| Küçük floating panel | `Popover` |
+| Tooltip açıklama | `Tooltip` |
+| Büyük overlay/modal | `Dialog` veya `Modal` |
+| Yan panel | `Sheet` |
+| Mobil bottom drawer | `Drawer` |
+| Global search | `CommandPalette` |
+| Segmented nav | `Tabs` |
+| Dashboard tablo | `DataTable` |
+| App navbar | `Navbar` |
+| Dashboard sidebar | `Sidebar` |
+| Site footer | `Footer` |
+| Duyuru barı | `AnnouncementBar` |
+| Blog kartı | `ArticleCard` veya `NewsCard` |
+| Proje kartı | `ImageCard` |
+| Metrik kartı | `StatsCard` |
+| Referans kartı | `TestimonialCard` |
+| Fiyatlandırma | `PricingCard` veya `PricingPlanCard` |
+
+---
+
+## 16. Kaçınılması gerekenler
+
+AI şunları yapmamalı:
+
+- Poyraz UI componenti varken sıfırdan custom Dropdown/Dialog/Tabs yazmamalı.
+- `div` ile button gibi davranan element yapmamalı.
+- Focus outline/ring’i silmemeli.
+- Hard-coded dark/light renkleri çoğaltmamalı.
+- Çok fazla shadow eklememeli.
+- Buttonlarda swap/fill gibi effectler için custom CSS yazmamalı; prop kullanmalı.
+- Form validation mesajlarını sadece toast ile vermemeli.
+- `asChild` kullanırken Button effect anatomy’sini bozacak nested yapılar kurmamalı.
+- Component variantlarını bilmeden uydurmamalı; bu dokümandaki variant değerlerine bağlı kalmalı.
+
+---
+
+## 17. Başka projede kullanım için örnek AI prompt
+
+Aşağıdaki prompt’u başka bir projede AI’a verebilirsin:
+
+```md
+Bu projede poyraz-ui kullanarak UI geliştir.
+
+Kurulum:
+- Eğer yoksa `poyraz-ui@3` kur.
+- Global CSS içinde `@import "poyraz-ui/preset.css";` olduğundan emin ol.
+
+Import:
+- Atoms: `poyraz-ui/atoms`
+- Molecules: `poyraz-ui/molecules`
+- Organisms: `poyraz-ui/organisms`
+
+Tasarım dili:
+- Minimal, soft, hafif rounded, clean border, gölgesiz veya çok düşük gölgeli.
+- Semantic token kullan: `bg-background`, `text-foreground`, `text-muted-foreground`, `border-border`, `bg-card`, `text-primary`.
+- Gereksiz custom CSS yazma.
+
+Button:
+- CTA butonlarında `effect="swap"` kullan.
+- `ButtonLabel` ve `ButtonIcon` kullan.
+- Icon-only buttonlarda aria-label ekle.
+
+Form:
+- Input için `Input`, `Textarea`, `PhoneInput`, `UrlInput`, `PasswordInput`, `SearchInput` kullan.
+- Form validation varsa `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormMessage` kullan.
+
+Overlay:
+- Dropdown için `DropdownMenu`
+- Dialog/modal için `Dialog` veya `Modal`
+- Yan panel için `Sheet`
+- Mobil drawer için `Drawer`
+- Global search için `CommandPalette`
+
+Layout:
+- Navbar için `Navbar`
+- Sidebar için `Sidebar`
+- Footer için `Footer`
+- Duyuru için `AnnouncementBar`
+- Tablo için `DataTable`
+
+Her componenti erişilebilir ve responsive kur.
+```
+
+---
+
+## 18. Minimal starter örneği
+
+```tsx
+import "poyraz-ui/preset.css";
+
+import { Button, ButtonIcon, ButtonLabel, Card, CardContent, Typography } from "poyraz-ui/atoms";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "poyraz-ui/molecules";
+
+export default function Page() {
+  return (
+    <main className="min-h-screen bg-background text-foreground">
+      <section className="mx-auto max-w-5xl space-y-8 px-6 py-12">
+        <div className="space-y-3">
+          <Typography variant="h1" component="h1">
+            Poyraz UI Starter
+          </Typography>
+          <Typography variant="lead" className="text-muted-foreground">
+            Minimal, soft ve token bazlı React arayüzü.
+          </Typography>
+          <Button effect="swap" swapTarget="both">
+            <ButtonLabel>Başla</ButtonLabel>
+            <ButtonIcon>→</ButtonIcon>
+          </Button>
+        </div>
+
+        <Card>
+          <CardContent className="p-4">
+            <Tabs defaultValue="one">
+              <TabsList>
+                <TabsTrigger value="one">Overview</TabsTrigger>
+                <TabsTrigger value="two">Settings</TabsTrigger>
+              </TabsList>
+              <TabsContent value="one">Overview content</TabsContent>
+              <TabsContent value="two">Settings content</TabsContent>
+            </Tabs>
+          </CardContent>
+        </Card>
+      </section>
+    </main>
+  );
+}
+```
+
+---
+
+## 19. Registry component adları
+
+Source registry üzerinden eklenebilen component/block adları:
+
+### Atoms
+
+```txt
+avatar
+badge
+bg-pattern
+button
+card
+checkbox
+form-fields
+input
+label
+logo
+radio-group
+scroll-area
+separator
+skeleton
+switch
+textarea
+typography
+```
+
+### Molecules
+
+```txt
+accordion
+alert
+autocomplete
+breadcrumb
+calendar
+command-palette
+date-picker
+dialog
+drawer
+dropdown-menu
+form
+hover-card
+mermaid
+modal
+pagination
+popover
+select
+sheet
+sonner
+star-rating
+tabs
+tooltip
+```
+
+### Organisms
+
+```txt
+announcement-bar
+data-table
+footer
+navbar
+sidebar
+```
+
+### Blocks
+
+```txt
+article-card
+auth-card-block
+brand-hero-block
+dashboard-shell-block
+footer-blocks
+glass-app-shell-block
+image-card
+mega-menu-block
+mobile-navigation-block
+mobile-sidebar-block
+navigation-block
+news-card
+pricing-block
+pricing-card
+product-card
+smart-dashboard-block
+stats-card
+testimonial-card
+```
+
+Registry install örneği:
+
+```bash
+pnpm dlx shadcn@latest add @poyraz/button
+pnpm dlx shadcn@latest add @poyraz/dropdown-menu
+pnpm dlx shadcn@latest add @poyraz/brand-hero-block
+```
+
+---
+
+## 20. Son kontrol listesi
+
+Başka projede poyraz-ui kullanırken AI şu checklist’i uygulamalı:
+
+- [ ] `poyraz-ui@3` kurulu mu?
+- [ ] `@import "poyraz-ui/preset.css";` global CSS’te var mı?
+- [ ] Componentler doğru entry point’ten import ediliyor mu?
+- [ ] Tasarım semantic tokenlarla mı kurulmuş?
+- [ ] Button effectleri prop ile mi verilmiş?
+- [ ] Form alanlarında label ve error state var mı?
+- [ ] Overlay componentlerinde Title/Description kullanılmış mı?
+- [ ] Icon-only buttonlarda `aria-label` var mı?
+- [ ] Dark mode’da hard-coded renk problemi yok mu?
+- [ ] Gereksiz custom CSS yazılmadı mı?
+- [ ] Responsive grid/stack davranışı tanımlı mı?
+- [ ] Keyboard/focus erişilebilirliği korunuyor mu?
diff --git a/docs/self-hosted-redesign/neta-self-hosted-v3-master-plan.md b/docs/self-hosted-redesign/neta-self-hosted-v3-master-plan.md
new file mode 100644
index 0000000..cf58c5c
--- /dev/null
+++ b/docs/self-hosted-redesign/neta-self-hosted-v3-master-plan.md
@@ -0,0 +1,1028 @@
+---
+title: Neta Self-Hosted v3 Ana Dönüşüm Planı
+description: Supabase çıkışı, SQLite tabanlı backend, Better Auth, Poyraz UI v3 ve instance özelleştirmesi için ana yol haritası.
+status: active
+last_updated: 2026-07-16
+---
+
+# Neta Self-Hosted v3 Ana Dönüşüm Planı
+
+## 1. Belgenin amacı
+
+Bu belge Neta'nın mevcut Supabase tabanlı uygulamadan tamamen self-hosted, tek instance çalışabilen ve hafif bir mimariye taşınması için ana uygulama planıdır.
+
+Plan üç ana hedefi birlikte ele alır:
+
+1. Supabase Auth, Postgres, Storage ve RLS bağımlılıklarını tamamen kaldırmak.
+2. UI katmanını yalnızca Poyraz UI v3 tabanlı olacak şekilde sayfa sayfa yenilemek.
+3. Self-host eden kişinin Neta'yı logo, renk, tema ve temel marka bilgileriyle özelleştirebilmesini sağlamak.
+
+Bu belge yalnızca teknik görev listesi değildir. Mimari kararları, faz bağımlılıklarını, kalite kapılarını, sayfa bazlı çalışma yöntemini, production cutover sürecini ve gelecekteki mobil istemciye hazırlık sınırlarını da tanımlar.
+
+## 2. Ürün hedefi
+
+Neta; freelancer'ın müşterilerini, projelerini, görevlerini, takvimini, finansını, günlük kayıtlarını ve müşteri portalını tek bir self-hosted çalışma alanında yönetmesini sağlamalıdır.
+
+İlk self-hosted sürümün ana özellikleri:
+
+- Tek komut veya standart Docker akışıyla kurulabilmesi.
+- Harici BaaS zorunluluğu olmaması.
+- Uygulama verileri ve dosyalarının tek persistent volume altında tutulabilmesi.
+- İlk freelancer/admin hesabının güvenli kurulum akışıyla oluşturulması.
+- Müşterilerin davet edilerek kendi portal hesaplarını oluşturabilmesi.
+- Tüm UI'ın Poyraz UI v3 tasarım sistemiyle tutarlı olması.
+- Uygulama adı, logo ve renklerin kod değiştirmeden özelleştirilebilmesi.
+- Gelecekte React Native istemcisinin bağlanabileceği stabil bir backend sınırı bulunması.
+
+## 3. Kapsam dışı hedefler
+
+İlk self-hosted sürümde aşağıdaki hedefler zorunlu değildir:
+
+- Horizontal scaling veya aynı SQLite dosyasına yazan birden fazla uygulama instance'ı.
+- Offline-first senkronizasyon.
+- PWA cache ve background sync.
+- Supabase ile production dual-write.
+- Mobil uygulamanın kendisi.
+- Mobil cihaz pairing/token akışının tamamı.
+- Runtime pgvector veya harici vector database.
+- Takım/organization modeli, aksi ayrıca kararlaştırılmadıkça.
+
+## 4. Kilitlenen ürün kararları
+
+Bu maddeler Faz 0 kapsamında ADR-0013–ADR-0017 ile kilitlenmiştir.
+
+- [x] Bir Neta instance'ının tek freelancer/admin sahibi olacağı onaylandı.
+- [x] Birden fazla freelancer veya ekip desteğinin ilk sürüm kapsamı dışında olduğu onaylandı.
+- [x] Mevcut Supabase production verisinin korunacağı belirlendi.
+- [x] Production veri miktarından bağımsız olarak tek seferlik import aracının zorunlu kapsam olduğu onaylandı.
+- [x] Teklifler modülünün kaynak verisinin korunacağı, ancak UI/CRUD tamamlamasının release-blocker olmayacağı belirlendi.
+- [x] Sözleşmeler modülünün kaynak verisinin korunacağı, ancak UI/CRUD tamamlamasının release-blocker olmayacağı belirlendi.
+- [x] Faturalar modülünün kaynak verisinin korunacağı, ancak UI/CRUD tamamlamasının release-blocker olmayacağı belirlendi.
+- [x] Abonelikler modülünün kaynak verisinin korunacağı, ancak UI/CRUD tamamlamasının release-blocker olmayacağı belirlendi.
+- [x] Müşteri iletişiminin ilk sürümde proje görünürlüğü, public görevler ve revizyon talepleriyle sınırlı kalacağı belirlendi.
+- [x] Poyraz UI kullanım modeli npm package olarak onaylandı.
+
+Kilitlenen ilk sürüm kararı:
+
+- Tek owner/admin ve birden fazla client hesabı.
+- Poyraz UI v3 merkezi npm package kullanımı.
+- Çekirdek modüller tamamlanana kadar teklifler, sözleşmeler, faturalar ve aboneliklerin ikinci öncelik olması.
+- Müşteri portalında ilk aşamada proje görünürlüğü, public görevler ve güvenli revizyon akışı.
+
+## 5. Hedef sistem mimarisi
+
+```text
+Next.js Web UI                         Gelecekte React Native
+      |                                         |
+      | Server Component / Server Action        | HTTPS / JSON
+      v                                         v
+                Next.js uygulama sınırı
+                         |
+             +-----------+-----------+
+             |                       |
+       Web adapter'ları         /api/v1 Route Handlers
+             |                       |
+             +-----------+-----------+
+                         |
+                  Service katmanı
+                         |
+             Authorization + Validation
+                         |
+              +----------+----------+
+              |                     |
+        Repository katmanı      File service
+              |                     |
+              v                     v
+       SQLite + Drizzle       /app/data/uploads
+```
+
+### 5.1. Temel mimari kurallar
+
+- Server Component'ler okuma işlemlerinde service/repository katmanını doğrudan kullanabilir.
+- Server Action'lar mutation için aynı service katmanını kullanır.
+- Route Handler'lar mobil ve harici istemciler için aynı service katmanına adapter olur.
+- Web uygulaması kendi backend'ine gereksiz internal HTTP çağrısı yapmaz.
+- İş kuralları Server Action veya Route Handler içine gömülmez.
+- Browser tarafı veritabanı, auth secret, filesystem veya server-only modül import etmez.
+- Repository fonksiyonları kullanıcı/actor bağlamı olmadan owner'a bağlı veri döndürmez.
+- SQLite üzerinde RLS olmadığı için yetkilendirme her service/repository işleminde açıkça uygulanır.
+- Tüm dış girdiler Zod veya eşdeğer merkezi schema ile doğrulanır.
+- Yetkisiz kaynak erişiminde mümkün olduğunda kaynağın varlığı sızdırılmaz.
+
+### 5.2. Önerilen sunucu klasör yapısı
+
+```text
+server/
+  auth/
+    auth.ts
+    session.ts
+    authorization.ts
+    invitations.ts
+
+  db/
+    client.ts
+    transaction.ts
+    schema/
+    migrations/
+
+  repositories/
+    clients.ts
+    projects.ts
+    tasks.ts
+    calendar.ts
+    finance.ts
+    journal.ts
+    portal.ts
+    chat.ts
+    settings.ts
+
+  services/
+    clients/
+    projects/
+    tasks/
+    finance/
+    portal/
+    files/
+    branding/
+    analytics/
+
+  api/
+    schemas/
+    responses.ts
+    errors.ts
+
+  files/
+    paths.ts
+    validation.ts
+    authorization.ts
+```
+
+## 6. Veri modeli standartları
+
+- ID'ler mevcut Supabase UUID değerlerini koruyabilmek için text/UUID uyumlu tutulur.
+- Para alanları integer minor unit olarak saklanır.
+- Para birimleri satır bazında ISO benzeri kodla tutulur.
+- İş tarihleri `YYYY-MM-DD` formatında tutulabilir.
+- Sistem timestamp'leri UTC standardında saklanır.
+- Her owner'a bağlı tabloda açık bir `owner_user_id` ilişkisi bulunur.
+- Client erişimi `clients.auth_user_id` veya eşdeğer ilişki üzerinden kurulur.
+- Status alanları serbest metin yerine doğrulanmış enum/union sözleşmesine sahip olur.
+- Dosya içeriği DB'de tutulmaz; DB yalnızca metadata ve relative path tutar.
+- AI API key'leri browser'a veya `localStorage` alanına çıkarılmaz.
+- AI API key'leri düz metin migration ile taşınmaz.
+
+## 7. Hedef domain tabloları
+
+### 7.1. Platform ve auth
+
+- Better Auth `user`
+- Better Auth `session`
+- Better Auth `account`
+- Better Auth `verification`
+- `app_profiles`
+- `app_setup_state`
+- `auth_audit_events`
+- `portal_invitations`
+- `device_tokens` veya pairing tabloları, yalnızca mobil fazında
+
+### 7.2. Instance ve kullanıcı ayarları
+
+- `instance_settings`
+- `instance_branding`
+- `user_preferences`
+- `user_ai_settings` veya server-side secret referansları
+
+### 7.3. Çekirdek iş verileri
+
+- `clients`
+- `client_activities`
+- `projects`
+- `project_planning_sections`
+- `tasks`
+- `calendar_events`
+- `finance_transactions`
+- `journal_entries`
+- `project_revisions`
+- `files`
+- `chat_sessions`
+- `chat_messages`
+
+### 7.4. Kapsama göre taşınacak iş modülleri
+
+- `proposals`
+- `contracts`
+- `invoices`
+- `subscriptions`
+
+## 8. Better Auth ve kullanıcı akışları
+
+### 8.1. İlk freelancer/admin kurulumu
+
+- [x] Public registration ilk admin sonrasında kapanıyor.
+- [x] Kurulum kilidi eşzamanlı isteklere karşı transaction ile korunuyor.
+- [x] İlk kullanıcı `freelancer` rolüyle profile bağlanıyor.
+- [x] Kurulum başarısızlığında stale lock onarılabiliyor.
+- [x] Başarılı ve başarısız auth olayları audit tablosuna yazılıyor.
+- [x] Production'da güçlü `BETTER_AUTH_SECRET` zorunlu.
+- [x] Trusted origin ve secure cookie kontrolleri doğrulandı.
+
+### 8.2. Müşteri davet akışı
+
+Önerilen akış:
+
+1. Freelancer bir müşteri kaydı oluşturur.
+2. Freelancer “Portala davet et” aksiyonunu kullanır.
+3. Sistem süreli ve tek kullanımlık bir token üretir.
+4. Veritabanında token'ın yalnızca hash'i saklanır.
+5. Müşteri davet bağlantısını açar ve kendi şifresini belirler.
+6. Better Auth kullanıcısı ve `client` profili oluşturulur.
+7. Kullanıcı ilgili müşteri kaydına transaction içinde bağlanır.
+8. Davet `accepted` durumuna alınır.
+
+Checklist:
+
+- [x] Davet oluşturma yetkisi yalnızca freelancer/admin rolünde.
+- [x] Davet token'ı kriptografik olarak güvenli.
+- [x] Token düz metin olarak DB'de saklanmıyor.
+- [x] Davetin son kullanma tarihi var.
+- [x] Davet iptal edilebiliyor.
+- [x] Aynı müşteri için aktif davet politikası tanımlandı.
+- [x] Kabul işlemi transaction içinde.
+- [x] Client profile ve client kimlik bağı atomik kuruluyor (`app_profiles.client_id`; domain FK Faz 2'de eklenecek).
+- [x] Kullanılmış veya süresi dolmuş token tekrar kullanılamıyor.
+- [x] Client hesabı disable/revoke edilebiliyor.
+
+## 9. Server-side authorization matrisi
+
+Her resource için pozitif ve negatif test yazılmalıdır.
+
+| Resource | Freelancer | Client | Zorunlu negatif test |
+| --- | --- | --- | --- |
+| Profiles | Kendi profili | Kendi profili | Başka profil reddedilir |
+| Clients | Kendi müşterileri CRUD | Bağlı müşteri kaydını read | Başka müşteri reddedilir |
+| Projects | Kendi projeleri CRUD | Bağlı projeleri read | Başka proje reddedilir |
+| Tasks | Kendi görevleri CRUD | Bağlı projelerde public görevler | Private görev reddedilir |
+| Planning sections | Kendi bölümleri CRUD | Bağlı proje bölümleri read | Başka proje reddedilir |
+| Revisions | Kendi proje revizyonlarını yönetir | Kendi projesine talep ekler/read | Project-client uyuşmazlığı reddedilir |
+| Calendar | Kendi etkinlikleri CRUD | Erişim yok | Client rolü reddedilir |
+| Finance | Kendi kayıtları CRUD | Erişim yok | Client rolü reddedilir |
+| Journal | Kendi kayıtları CRUD | Erişim yok | Client rolü reddedilir |
+| Chat | Kendi session/message kayıtları | İlk sürümde erişim yok | Başka session reddedilir |
+| Settings | Kendi tercihleri | Kendi tercihleri | Secret browser'a dönmez |
+| Branding | Admin düzenler | Read-only marka çıktısı | Client mutation reddedilir |
+| Files | İlişkili kaynağa göre | İlişkili portal kaynağına göre | Path traversal ve başka owner reddedilir |
+
+## 10. Yerel dosya sistemi
+
+Hedef klasör yapısı:
+
+```text
+/app/data/
+  neta.db
+  uploads/
+    avatars/
+    branding/
+    project-assets/
+  backups/
+  tmp/
+```
+
+Dosya checklist'i:
+
+- [ ] Dosya metadata tablosu oluşturuldu.
+- [ ] Relative path dışında mutlak kullanıcı girdisi kullanılmıyor.
+- [ ] Path traversal koruması var.
+- [ ] Dosya boyutu limiti var.
+- [ ] MIME allowlist var.
+- [ ] Gerekli türlerde magic-byte doğrulaması var.
+- [ ] SVG kabul ediliyorsa sanitizasyon kararı uygulandı.
+- [ ] Yetkili upload Route Handler yazıldı.
+- [ ] Yetkili download Route Handler yazıldı.
+- [ ] Public branding asset'leri ayrı ve kontrollü sunuluyor.
+- [ ] Project asset erişimi owner/project/client ilişkisiyle doğrulanıyor.
+- [ ] Dosya silme ve DB metadata işlemi tutarlı.
+- [ ] Backup içine upload klasörü dahil.
+
+## 11. Instance özelleştirme ve tema
+
+### 11.1. Instance markası
+
+İlk sürümde desteklenmesi önerilen ayarlar:
+
+- Uygulama adı
+- Kısa uygulama adı
+- Açık tema logosu
+- Koyu tema logosu
+- Uygulama ikonu/favicon
+- Primary renk
+- Accent renk
+- Varsayılan color mode
+- Radius yoğunluğu
+- Freelancer veya şirket adı
+- Destek e-postası
+- Portal karşılama metni
+- Portal footer metni
+
+### 11.2. Kullanıcı tercihleri
+
+- Light/dark/system görünüm
+- Sidebar açık/kapalı durumu
+- Dil
+- Saat dilimi
+- Varsayılan para birimi
+- Tarih formatı
+
+### 11.3. Önerilen branding sözleşmesi
+
+```ts
+type BrandingSettings = {
+  applicationName: string;
+  shortName: string;
+  primaryColor: string;
+  accentColor: string;
+  lightLogoFileId: string | null;
+  darkLogoFileId: string | null;
+  iconFileId: string | null;
+  defaultColorMode: "light" | "dark" | "system";
+  radiusScale: "compact" | "default" | "soft";
+};
+```
+
+Tema checklist'i:
+
+- [ ] Poyraz UI semantic tokenları kullanılıyor.
+- [ ] Marka ayarları root layout'ta server-side okunuyor.
+- [ ] İlk render sırasında tema/renk parlaması yok.
+- [ ] Primary ve accent renk girdileri doğrulanıyor.
+- [ ] Metin/zemin kontrastı kontrol ediliyor.
+- [ ] Hard-coded brand renkleri feature sayfalarına dağılmıyor.
+- [ ] Açık ve koyu modda logo fallback'i var.
+- [ ] Logo kaldırma ve varsayılana dönme desteği var.
+- [ ] Branding ayarlarına yalnızca freelancer/admin yazabiliyor.
+- [ ] Client portal aynı instance markasını güvenli biçimde kullanıyor.
+
+## 12. Poyraz UI v3 stratejisi
+
+Referans doküman: `docs/poyraz-ui-ai-consumer-guide.md`
+
+Referans paket: `poyraz-ui@3.0.2`
+
+### 12.1. Yeni UI kararı
+
+- Genel atom, molecule ve organism bileşenleri Poyraz UI v3'ten alınır.
+- Neta'ya özgü domain bileşenleri Poyraz UI bileşenlerinden compose edilir.
+- Aynı amaçla hem local primitive hem Poyraz UI componenti tutulmaz.
+- Poyraz UI componenti varken custom Dialog, Select, Dropdown, Tabs, Sheet veya Sidebar yazılmaz.
+- Tailwind utility classları layout ve domain düzeni için kullanılabilir.
+- Gereksiz custom CSS ve hard-coded renk kullanılmaz.
+
+### 12.2. Kurulum checklist'i
+
+- [ ] `poyraz-ui` v3'e yükseltildi.
+- [ ] `@import "poyraz-ui/preset.css";` global CSS'e eklendi.
+- [ ] Atom importları `poyraz-ui/atoms` üzerinden.
+- [ ] Molecule importları `poyraz-ui/molecules` üzerinden.
+- [ ] Organism importları `poyraz-ui/organisms` üzerinden.
+- [ ] Tema gerekiyorsa `poyraz-ui/themes` kullanımı değerlendirildi.
+- [x] Package modeli ana kullanım biçimi olarak belirlendi.
+- [x] Source registry yalnızca source ownership gereken istisnalar için kullanılacak.
+
+### 12.3. Ortak UI standartları
+
+- [ ] Typography hiyerarşisi tanımlandı.
+- [ ] Page header standardı tanımlandı.
+- [ ] Primary ve secondary action standardı tanımlandı.
+- [ ] Form field ve validation standardı tanımlandı.
+- [ ] Status-to-Badge eşleme tablosu oluşturuldu.
+- [ ] Loading state standardı oluşturuldu.
+- [ ] Empty state standardı oluşturuldu.
+- [ ] Error state standardı oluşturuldu.
+- [ ] Permission/forbidden state standardı oluşturuldu.
+- [ ] Destructive confirmation standardı oluşturuldu.
+- [ ] Desktop Dialog/Sheet ve mobil Drawer kullanım kuralı belirlendi.
+- [ ] Toast ve inline feedback ayrımı belirlendi.
+- [ ] DataTable kullanım standardı belirlendi.
+- [ ] Dashboard KPI kart standardı belirlendi.
+
+### 12.4. Erişilebilirlik kalite kapısı
+
+- [ ] Icon-only butonlarda `aria-label` var.
+- [ ] Icon-only aksiyonlarda gerektiğinde Tooltip var.
+- [ ] Tüm form alanlarında görünür Label var.
+- [ ] Placeholder, Label yerine kullanılmıyor.
+- [ ] Dialog, Modal, Sheet ve Drawer içinde Title var.
+- [ ] Form hataları yalnızca toast ile gösterilmiyor.
+- [ ] Focus ring custom classlarla kaldırılmıyor.
+- [ ] Keyboard navigation korunuyor.
+- [ ] Disabled ve loading state'leri doğru prop üzerinden veriliyor.
+- [ ] Light ve dark mod kontrastları kontrol edildi.
+- [ ] Reduced-motion tercihleri göz önünde tutuldu.
+
+## 13. Sayfa bazlı çalışma yöntemi
+
+Her sayfa bir dikey dilim olarak tamamlanır. Yalnızca görünüm değiştirilmiş veya yalnızca backend'i taşınmış yarım sayfa tamamlanmış sayılmaz.
+
+Her sayfa için uygulanacak süreç:
+
+1. Kullanıcı sayfanın amacını ve istenen UX'i tarif eder.
+2. Bilgi hiyerarşisi ve ana kullanıcı aksiyonları netleştirilir.
+3. Sayfanın veri sözleşmesi çıkarılır.
+4. Repository ve service işlemleri tamamlanır.
+5. Server Component sorguları ve Server Action mutation'ları yazılır.
+6. Gerekli `/api/v1` sözleşmeleri eklenir veya hazırlanır.
+7. Sayfa Poyraz UI v3 ile tasarlanır.
+8. Loading, empty, error ve permission state'leri eklenir.
+9. Responsive ve keyboard davranışı doğrulanır.
+10. Pozitif ve negatif testler çalıştırılır.
+11. Kullanıcı kabulünden sonra sonraki sayfaya geçilir.
+
+### 13.1. Sayfa kabul checklist'i
+
+Her sayfa için bu şablon kopyalanmalıdır:
+
+- [ ] Sayfanın amacı yazıldı.
+- [ ] Birincil kullanıcı aksiyonu belirlendi.
+- [ ] İkincil aksiyonlar belirlendi.
+- [ ] Bilgi hiyerarşisi onaylandı.
+- [ ] Veri okuma sözleşmesi oluşturuldu.
+- [ ] Mutation sözleşmeleri oluşturuldu.
+- [ ] Owner/role kontrolleri tamamlandı.
+- [ ] Input validation tamamlandı.
+- [ ] Poyraz UI v3 bileşenleri kullanıldı.
+- [ ] Custom primitive eklenmedi.
+- [ ] Loading state tamamlandı.
+- [ ] Empty state tamamlandı.
+- [ ] Error state tamamlandı.
+- [ ] Permission state tamamlandı.
+- [ ] Mobil görünüm doğrulandı.
+- [ ] Tablet görünüm doğrulandı.
+- [ ] Desktop görünüm doğrulandı.
+- [ ] Keyboard kullanımı doğrulandı.
+- [ ] Light mode doğrulandı.
+- [ ] Dark mode doğrulandı.
+- [ ] Typecheck geçti.
+- [ ] İlgili testler geçti.
+- [ ] Kullanıcı kabulü alındı.
+
+## 14. Önerilen sayfa dönüşüm sırası
+
+### 14.1. Temel deneyim
+
+- [ ] İlk kurulum sayfası
+- [ ] Login sayfası
+- [ ] Şifremi unuttum akışı
+- [ ] Global app shell
+- [ ] Sidebar ve mobil navigation
+- [ ] Hesap menüsü ve çıkış
+- [ ] Ayarlar ana sayfası
+- [ ] Marka ve tema özelleştirme sayfası
+- [ ] Profil ve şifre ayarları
+
+### 14.2. Müşteri yönetimi
+
+- [ ] Müşteri listesi
+- [ ] Müşteri oluşturma/düzenleme
+- [ ] CRM pipeline görünümü
+- [ ] Müşteri detay sayfası
+- [ ] Müşteri aktivite geçmişi
+- [ ] Portal davet durumu ve aksiyonları
+
+### 14.3. Proje ve görev yönetimi
+
+- [ ] Proje listesi
+- [ ] Proje oluşturma/düzenleme
+- [ ] Proje detay genel bakış
+- [ ] Proje planlama bölümleri
+- [ ] Proje design system bölümleri
+- [ ] Proje dosyaları/kapak görseli
+- [ ] Proje görevleri
+- [ ] Proje finans özeti
+- [ ] Proje revizyon yönetimi
+- [ ] Genel görev listesi
+- [ ] Kanban görünümü
+- [ ] Görev filtreleri ve arama
+
+### 14.4. Operasyon ve kişisel takip
+
+- [ ] Takvim
+- [ ] Etkinlik oluşturma/düzenleme
+- [ ] Finans listesi
+- [ ] Gelir/gider oluşturma/düzenleme
+- [ ] Finans filtreleri ve özetleri
+- [ ] Günlük listesi
+- [ ] Günlük oluşturma/düzenleme
+
+### 14.5. Özet ve analiz
+
+- [ ] Dashboard
+- [ ] Dashboard tarih aralığı
+- [ ] Analytics
+- [ ] Aggregate repository sorguları
+- [ ] Grafikler ve erişilebilir veri özetleri
+
+### 14.6. Müşteri portalı
+
+- [ ] Portal davet kabul sayfası
+- [ ] Portal shell
+- [ ] Portal dashboard
+- [ ] Portal proje listesi
+- [ ] Portal proje detayı
+- [ ] Public görev görünümü
+- [ ] Planlama bölümleri görünümü
+- [ ] Revizyon talebi oluşturma
+- [ ] Revizyon geçmişi
+- [ ] Portal hesap ayarları
+
+### 14.7. AI
+
+- [ ] AI provider ayarlarının server-only hale getirilmesi
+- [ ] AI chat session listesi
+- [ ] AI chat mesaj ekranı
+- [ ] Kullanıcı verisi context builder
+- [ ] Finans analizi
+- [ ] Proje risk analizi
+- [ ] Provider hata ve timeout yönetimi
+- [ ] Kullanıcıya veri paylaşımı/gizlilik açıklaması
+
+### 14.8. Opsiyonel business modülleri
+
+- [ ] Teklifler
+- [ ] Sözleşmeler
+- [ ] Faturalar
+- [ ] Abonelikler
+
+## 15. Revizyon güvenliği ve kota işlemi
+
+Revizyon oluşturma yalnızca UI kontrolüne dayanamaz.
+
+Transaction içinde doğrulanacaklar:
+
+- Actor `client` rolünde mi?
+- Actor hangi client record'a bağlı?
+- Project gerçekten bu client record'a mı bağlı?
+- Proje revizyon kabul ediyor mu?
+- Kalan revision quota yeterli mi?
+- Açık revizyon politikası sağlanıyor mu?
+- Insert ile quota güncellemesi aynı transaction içinde mi?
+
+Checklist:
+
+- [ ] `project_id` ve `client_id` eşleşmesi server-side doğrulanıyor.
+- [ ] İstemciden gelen `clientId` güven kaynağı olarak kullanılmıyor.
+- [ ] Quota server-side kontrol ediliyor.
+- [ ] Quota atomik azaltılıyor veya tüketim kayıtlarından hesaplanıyor.
+- [ ] Başarısız insert quota tüketmiyor.
+- [ ] Cross-project revision negatif testi var.
+- [ ] Başka client adına revision oluşturma negatif testi var.
+- [ ] Kota aşımı negatif testi var.
+
+## 16. API v1 ve mobil hazırlığı
+
+Mobil uygulama ilk sürüm kapsamında değildir; ancak backend web'e özel bir çıkmaza sokulmamalıdır.
+
+Önerilen başlangıç endpoint'leri:
+
+```text
+GET  /.well-known/neta
+GET  /api/v1/meta
+GET  /api/v1/health
+GET  /api/v1/me
+```
+
+Gelecekte:
+
+```text
+POST /api/v1/pairing-codes
+POST /api/v1/device-sessions/exchange
+GET  /api/v1/device-sessions
+DELETE /api/v1/device-sessions/:id
+```
+
+Mobil hazırlık checklist'i:
+
+- [ ] API response envelope standardı tanımlandı.
+- [ ] API hata kodları tanımlandı.
+- [ ] API sürümleme stratejisi tanımlandı.
+- [ ] Instance metadata sözleşmesi tanımlandı.
+- [ ] Minimum desteklenen client sürümü alanı düşünüldü.
+- [ ] Capability listesi sözleşmesi düşünüldü.
+- [ ] Service katmanı cookie/Next.js objelerine bağımlı değil.
+- [ ] Mobil pairing ilk release kapsamı dışında tutuldu.
+- [ ] Gelecekte HTTPS zorunluluğu belgelendi.
+
+## 17. Supabase veri import ve cutover planı
+
+### 17.1. Import aracı
+
+- [ ] Supabase tablolarının kaynak mapping'i güncellendi.
+- [ ] Export formatı tanımlandı.
+- [ ] Import dry-run modu var.
+- [ ] Kaynak ve hedef satır sayıları raporlanıyor.
+- [ ] Foreign key tutarsızlıkları raporlanıyor.
+- [ ] Bilinmeyen enum/status değerlerinde import fail ediyor.
+- [ ] `completed` görev status'ü `done` olarak normalize ediliyor.
+- [ ] Para değerleri minor unit'e güvenli dönüştürülüyor.
+- [ ] `journals` ve `daily_logs` merge kuralı uygulanıyor.
+- [ ] AI API key'leri taşınmıyor.
+- [ ] Auth password/session verileri taşınmıyor.
+- [ ] Client kullanıcıları yeniden davet ediliyor.
+- [ ] Storage dosyaları metadata ve checksum ile aktarılıyor.
+- [ ] Import tekrar çalıştırıldığında davranış tanımlı.
+
+### 17.2. Production cutover
+
+- [ ] Production backup alındı.
+- [ ] Supabase uygulaması maintenance/read-only moda alındı.
+- [ ] Son export alındı.
+- [ ] Import dry-run başarılı.
+- [ ] Final import başarılı.
+- [ ] Satır sayısı doğrulandı.
+- [ ] Dosya sayısı ve checksum doğrulandı.
+- [ ] İlk admin Better Auth hesabı hazırlandı.
+- [ ] Client re-invite planı hazırlandı.
+- [ ] Kritik kullanıcı akışları smoke test edildi.
+- [ ] DNS/deploy geçişi yapıldı.
+- [ ] Rollback penceresi ve yöntemi belgelendi.
+- [ ] Supabase hemen silinmedi; tanımlı süre read-only backup olarak tutuldu.
+
+## 18. Dependency azaltma planı
+
+### 18.1. Supabase çıkışı tamamlandığında kaldırılacaklar
+
+- [ ] `@supabase/ssr`
+- [ ] `@supabase/supabase-js`
+- [ ] `lib/supabase/*`
+- [ ] Legacy Supabase auth helper'ları
+- [ ] Supabase service-role client kullanımları
+- [ ] Runtime Supabase environment değişkenleri
+
+### 18.2. Offline/PWA temizliği
+
+- [ ] `@ducanh2912/next-pwa`
+- [ ] `dexie`
+- [ ] `dexie-react-hooks`
+- [ ] Legacy `lib/db.ts`
+- [ ] Offline indicator, kapsam dışıysa
+- [ ] Service worker çıktıları
+- [ ] PWA manifest kararı güncellendi
+
+### 18.3. Poyraz UI v3 sonrası değerlendirilecekler
+
+- [ ] `@base-ui/react`
+- [ ] Doğrudan `@radix-ui/*` bağımlılıkları
+- [ ] `radix-ui`
+- [ ] `shadcn`
+- [ ] Kullanılmayan local UI primitive'leri
+- [ ] `framer-motion`, kullanım kalmadıysa
+- [ ] `next-themes`, tema başka şekilde çözüldüyse
+- [ ] Kullanılmayan icon/form/theme yardımcıları
+
+### 18.4. İşlevsel gerekçeyle korunabilecekler
+
+- Next.js ve React
+- Poyraz UI v3
+- Better Auth
+- `better-sqlite3`
+- Drizzle ORM
+- Zod
+- `date-fns`
+- Kanban için `dnd-kit`
+- Grafikler için Recharts
+- Gerçekten kullanılan AI provider paketleri
+
+Dependency kalite kapısı:
+
+- [ ] Her production dependency için aktif import veya açık gerekçe var.
+- [ ] Aynı işi yapan iki UI primitive sistemi yok.
+- [ ] Aynı işi yapan iki auth sistemi yok.
+- [ ] Aynı işi yapan iki runtime database sistemi yok.
+- [ ] Browser database bağımlılığı yok.
+- [ ] Build çıktısında Supabase referansı yok.
+- [ ] Build çıktısında Poyraz UI v2 referansı yok.
+
+## 19. Test stratejisi
+
+Mümkün olduğunda küçük ve doğrudan test araçları tercih edilir; test altyapısı production dependency sayısını artırmamalıdır.
+
+### 19.1. Zorunlu test alanları
+
+- [x] Migration smoke testi
+- [x] SQLite pragma ve readiness testi
+- [x] İlk admin setup testi
+- [x] Concurrent setup lock testi
+- [x] Login/logout testi
+- [x] Client invitation testi
+- [x] Expired/revoked invitation negatif testi
+- [ ] Her repository için cross-owner negatif test
+- [ ] Client private task erişim negatif testi
+- [ ] Revision project-client eşleşme negatif testi
+- [ ] Revision quota testi
+- [ ] File upload MIME/size testi
+- [ ] Path traversal negatif testi
+- [x] Backup oluşturma testi
+- [ ] Restore ve checksum testi
+- [ ] Supabase import fixture testi
+- [ ] API response/error contract testi
+- [ ] Kritik sayfalar için SSR smoke testi
+
+### 19.2. Her faz sonunda çalıştırılacak kalite kapıları
+
+- [x] Typecheck başarılı.
+- [ ] Lint başarılı.
+- [x] Production build başarılı.
+- [x] İlgili smoke testler başarılı.
+- [x] Database migration temiz DB üzerinde başarılı.
+- [x] Mevcut DB üzerinde migration başarılı.
+- [x] `git diff --check` başarılı.
+- [x] Yeni secret veya kişisel veri repoya eklenmedi.
+
+## 20. Docker, backup ve operasyon
+
+- [x] Docker image standalone Next.js çıktısını kullanıyor.
+- [x] Uygulama non-root kullanıcıyla çalışıyor.
+- [x] `/app/data` persistent volume olarak bağlı.
+- [x] Startup migration deterministic.
+- [x] Migration hatasında uygulama başlamıyor.
+- [x] `BETTER_AUTH_SECRET` production'da zorunlu.
+- [x] Compose örneği gerekli tüm env alanlarını açıklıyor.
+- [x] Readiness endpoint DB ve migration durumunu kontrol ediyor.
+- [x] Liveness endpoint filesystem/DB bağımlılığı olmadan cevap veriyor.
+- [x] Backup SQLite online backup API kullanıyor.
+- [x] Backup upload klasörünü içeriyor.
+- [x] Backup manifest dosya boyutu ve SHA-256 içeriyor.
+- [ ] Restore manifest checksum'larını doğruluyor.
+- [x] Restore canlı DB üzerine kontrolsüz yazmıyor.
+- [ ] Backup retention politikası belgelendi.
+- [ ] Reverse proxy ve HTTPS kurulumu belgelendi.
+
+## 21. Dokümantasyon planı
+
+- [ ] README yeni SQLite/Better Auth mimarisini anlatıyor.
+- [ ] Supabase'in artık runtime gereksinimi olmadığı açık.
+- [ ] Docker ile kurulum belgelendi.
+- [ ] Coolify/Dokploy kurulumu belgelendi.
+- [x] Environment değişkenleri güncellendi.
+- [x] İlk admin kurulumu belgelendi.
+- [x] Client invitation akışı belgelendi.
+- [ ] Branding ayarları belgelendi.
+- [x] Backup/restore belgelendi.
+- [ ] Upgrade/migration akışı belgelendi.
+- [ ] Mobil API sınırı belgelendi.
+- [ ] Eski ve çelişkili Supabase belgeleri archive veya kaldırıldı.
+- [ ] ADR-0006 Poyraz UI v3 kararıyla güncellendi.
+- [ ] ADR-0007 ile PWA runtime durumu uyumlu hale getirildi.
+
+## 22. Uygulama fazları
+
+### Faz 0 — Karar ve baseline
+
+Amaç: Kapsamı kilitlemek ve dönüşüm sırasında korunacak davranışları tanımlamak.
+
+- [x] Bölüm 4'teki ürün kararları cevaplandı.
+- [x] Aktif route ve özellik envanteri güncellendi.
+- [ ] Supabase tablo ve storage veri sayıları çıkarıldı.
+- [x] Kritik kullanıcı akışları baseline olarak kaydedildi.
+- [x] Hedef schema mapping'i onaylandı.
+- [x] Yeni ADR seti güncellendi.
+- [x] Bu planın status alanı `active` yapıldı.
+
+Faz 0 ilerleme notu:
+
+- Repo/schema/fixture envanteri tamamlandı.
+- Production Supabase read-only erişimi veya export snapshot'ı workspace'te olmadığı için gerçek tablo satır sayıları, bucket dosya sayıları/boyutları ve orphan path raporu açık kaldı.
+- Audit sorguları `phase-0-data-mapping.md` içinde hazırdır. Bu dış veri sağlanmadan ilgili checkbox işaretlenmeyecektir.
+
+Çıkış kriteri: Veri kapsamı, ilk release modülleri ve tek/multi-owner kararı belirsiz değil.
+
+### Faz 1 — Runtime ve auth temelini tamamlama
+
+Amaç: Better Auth + SQLite çalışma zamanını production kullanıma hazır hale getirmek.
+
+- [x] İlk admin setup akışı tamamlandı.
+- [x] Session ve role guard'ları tamamlandı.
+- [x] Client invitation akışı tamamlandı.
+- [x] Auth audit kapsamı tamamlandı.
+- [x] Docker env sözleşmesi düzeltildi.
+- [x] Auth smoke ve negatif testleri geçti.
+
+Faz 1 tamamlanma notu (2026-07-16):
+
+- İlk owner yarışı, public registration kapanışı, doğrudan auth endpoint'i, login/logout ve stale setup onarımı doğrulandı.
+- Davet üretme, önceki aktif daveti otomatik iptal etme, hash-only token saklama, kabul, tekrar kullanım, expiry, manuel revoke ve client disable/enable akışları tamamlandı.
+- Davet kabulünde Better Auth `user`, credential `account`, `client` profile, `client_id` bağı ve davet durumu tek SQLite transaction'ında yazılıyor.
+- Client rolünün davet üretmesi ve disabled client'ın doğrudan Better Auth endpoint'inden session oluşturması negatif testlerle reddedildi.
+- `docker compose config` production secret/env sözleşmesiyle başarılıdır. Yerel Docker daemon çalışmadığı için container build/runtime smoke ayrıca doğrulanamamıştır; production Next.js standalone build başarıyla geçmiştir.
+- Cookie politikası canonical URL'ye bağlıdır: HTTPS'te `Secure`, local HTTP Docker kurulumunda kontrollü istisna; localhost dışındaki production HTTP URL'leri reddedilir.
+
+Çıkış kriteri: Freelancer ve davet edilmiş client Supabase Auth olmadan oturum açabiliyor.
+
+### Faz 2 — Domain schema ve backend çekirdeği
+
+Amaç: Tüm çekirdek iş verileri için Drizzle schema, migration, repository ve service katmanını kurmak.
+
+- [ ] Çekirdek tablolar oluşturuldu.
+- [ ] Repository katmanı oluşturuldu.
+- [ ] Service katmanı oluşturuldu.
+- [ ] Actor/authorization sözleşmesi standartlaştırıldı.
+- [ ] Validation ve error sözleşmesi standartlaştırıldı.
+- [ ] Negatif authorization testleri yazıldı.
+- [ ] Analytics aggregate sorgu yaklaşımı belirlendi.
+
+Çıkış kriteri: Çekirdek domain işlemleri UI veya Supabase'e bağımlı olmadan test edilebiliyor.
+
+### Faz 3 — Yerel storage ve branding temeli
+
+Amaç: Supabase Storage yerine güvenli local filesystem ve instance özelleştirmesi sağlamak.
+
+- [ ] File metadata schema tamamlandı.
+- [ ] Upload/download servisleri tamamlandı.
+- [ ] Avatar desteği tamamlandı.
+- [ ] Branding asset desteği tamamlandı.
+- [ ] Project asset desteği tamamlandı.
+- [ ] Instance branding schema ve service tamamlandı.
+- [ ] Server-rendered token uygulaması tamamlandı.
+
+Çıkış kriteri: Logo, avatar ve project asset için Supabase Storage gerekmiyor.
+
+### Faz 4 — Poyraz UI v3 foundation
+
+Amaç: Sayfa dönüşümleri başlamadan önce ortak UI sistemini kurmak.
+
+- [ ] Poyraz UI v3 kuruldu.
+- [ ] Preset CSS eklendi.
+- [ ] Global shell Poyraz Sidebar organism ile kuruldu.
+- [ ] Typography standardı tamamlandı.
+- [ ] Form standardı tamamlandı.
+- [ ] Feedback state'leri tamamlandı.
+- [ ] Tema/branding token bridge tamamlandı.
+- [ ] Local primitive kaldırma politikası uygulandı.
+
+Çıkış kriteri: Yeni sayfalar ek bir primitive sistemi oluşturmadan geliştirilebiliyor.
+
+### Faz 5 — Freelancer sayfalarının dikey dönüşümü
+
+Amaç: Her freelancer sayfasını backend ve UI ile birlikte Supabase'ten çıkarmak.
+
+- [ ] Temel deneyim sayfaları tamamlandı.
+- [ ] Müşteri sayfaları tamamlandı.
+- [ ] Proje sayfaları tamamlandı.
+- [ ] Görev sayfaları tamamlandı.
+- [ ] Takvim tamamlandı.
+- [ ] Finans tamamlandı.
+- [ ] Günlük tamamlandı.
+- [ ] Dashboard tamamlandı.
+- [ ] Analytics tamamlandı.
+
+Çıkış kriteri: Freelancer dashboard'u Supabase olmadan tam çalışıyor.
+
+### Faz 6 — Müşteri portalı
+
+Amaç: Better Auth client hesabı ve server-side authorization ile güvenli portalı tamamlamak.
+
+- [x] Portal davet kabulü tamamlandı.
+- [ ] Portal shell tamamlandı.
+- [ ] Portal proje ve görev görünümü tamamlandı.
+- [ ] Planning section görünümü tamamlandı.
+- [ ] Revision akışı ve quota transaction'ı tamamlandı.
+- [ ] Portal authorization negatif testleri geçti.
+- [ ] Portal branding tamamlandı.
+
+Çıkış kriteri: Client yalnızca kendi verisini görüyor ve güvenli revision talebi oluşturabiliyor.
+
+### Faz 7 — AI ve gelişmiş modüller
+
+Amaç: AI/chat ve kapsamda kalan business modüllerini yeni backend'e taşımak.
+
+- [ ] Chat session/message verileri SQLite'a taşındı.
+- [ ] AI secrets browser'dan kaldırıldı.
+- [ ] Context builder service katmanına taşındı.
+- [ ] Finans analizi taşındı.
+- [ ] Proje risk analizi taşındı.
+- [ ] Kapsamdaki business modülleri tamamlandı.
+
+Çıkış kriteri: Runtime AI özelliklerinde Supabase bağımlılığı yok.
+
+### Faz 8 — Import, temizlik ve release hardening
+
+Amaç: Production geçişini güvenli hale getirmek ve legacy bağımlılıkları kaldırmak.
+
+- [ ] Supabase import aracı tamamlandı.
+- [ ] Import rehearsal tamamlandı.
+- [ ] Supabase runtime paketleri kaldırıldı.
+- [ ] PWA/Dexie legacy kodu kaldırıldı.
+- [ ] Kullanılmayan UI bağımlılıkları kaldırıldı.
+- [ ] Backup/restore doğrulandı.
+- [ ] Docker production smoke tamamlandı.
+- [ ] Dokümantasyon güncellendi.
+- [ ] Cutover ve rollback provası tamamlandı.
+
+Çıkış kriteri: Uygulama Supabase environment değişkenleri olmadan build ve runtime smoke testini geçiyor.
+
+### Faz 9 — Mobil API hazırlığı
+
+Amaç: React Native geliştirmesine başlamadan önce instance keşif ve stabil API sınırını tamamlamak.
+
+- [ ] `/api/v1` sözleşmesi yayınlandı.
+- [ ] `/.well-known/neta` sözleşmesi yayınlandı.
+- [ ] Instance metadata ve capability modeli tamamlandı.
+- [ ] Pairing güvenlik tasarımı ayrı ADR olarak yazıldı.
+- [ ] Device token lifecycle tasarlandı.
+
+Çıkış kriteri: Mobil istemci backend'in iç uygulama detaylarına bağımlı olmadan entegrasyona başlayabilir.
+
+## 23. Genel ilerleme checklist'i
+
+### Mimari
+
+- [x] Ürün kararları kilitlendi.
+- [ ] Hedef schema tamamlandı.
+- [ ] Service/repository sınırı tamamlandı.
+- [ ] Server-side authorization tamamlandı.
+- [ ] API v1 sınırı hazırlandı.
+
+### Supabase çıkışı
+
+- [ ] Auth taşındı.
+- [ ] Database taşındı.
+- [ ] Storage taşındı.
+- [ ] RLS kuralları server-side testlere çevrildi.
+- [ ] Import aracı tamamlandı.
+- [ ] Supabase paketleri kaldırıldı.
+- [ ] Supabase env değişkenleri kaldırıldı.
+
+### UI
+
+- [ ] Poyraz UI v3 kuruldu.
+- [ ] Preset ve token sistemi kuruldu.
+- [ ] Global shell taşındı.
+- [ ] Freelancer sayfaları taşındı.
+- [ ] Portal sayfaları taşındı.
+- [ ] Local primitive tekrarı temizlendi.
+- [ ] Light/dark ve responsive kontroller tamamlandı.
+
+### Özelleştirme
+
+- [ ] Instance adı değiştirilebiliyor.
+- [ ] Logo yüklenebiliyor.
+- [ ] Favicon/ikon yüklenebiliyor.
+- [ ] Primary renk değiştirilebiliyor.
+- [ ] Accent renk değiştirilebiliyor.
+- [ ] Varsayılan tema değiştirilebiliyor.
+- [ ] Radius yoğunluğu değiştirilebiliyor.
+- [ ] Portal markası uygulanıyor.
+
+### Operasyon
+
+- [ ] Docker kurulumu çalışıyor.
+- [ ] Persistent volume doğrulandı.
+- [ ] Migration güvenli.
+- [ ] Backup çalışıyor.
+- [ ] Restore ve checksum doğrulaması çalışıyor.
+- [ ] Health endpoint'leri çalışıyor.
+- [ ] Upgrade dokümantasyonu hazır.
+- [ ] Rollback planı hazır.
+
+### Release
+
+- [ ] Typecheck başarılı.
+- [ ] Lint başarılı.
+- [ ] Build başarılı.
+- [ ] Tüm smoke testler başarılı.
+- [ ] Kritik authorization negatif testleri başarılı.
+- [ ] Import rehearsal başarılı.
+- [ ] Production Docker smoke başarılı.
+- [ ] README güncel.
+- [ ] Supabase runtime referansı kalmadı.
+- [ ] Poyraz UI v2 referansı kalmadı.
+
+## 24. Definition of Done
+
+Neta Self-Hosted v3 aşağıdaki koşulların tümü sağlandığında tamamlanmış kabul edilir:
+
+- Uygulama Supabase projesi veya Supabase environment değişkeni olmadan çalışır.
+- Tüm runtime iş verileri SQLite üzerinde tutulur.
+- Auth tamamen Better Auth üzerinden çalışır.
+- Freelancer ve client rol ayrımı server-side doğrulanır.
+- Müşteri davet akışı güvenlidir.
+- Portal cross-client veri erişimi negatif testlerle engellenmiştir.
+- Dosyalar local persistent volume altında güvenli biçimde tutulur.
+- Backup ve restore hem DB'yi hem dosyaları kapsar.
+- Tüm genel UI primitive'leri Poyraz UI v3 kullanır.
+- Tüm sayfalar loading, empty, error ve permission state'lerine sahiptir.
+- Uygulama adı, logo ve temel renkler yönetim ekranından değiştirilebilir.
+- Light/dark ve responsive davranışlar doğrulanmıştır.
+- Production Docker kurulumu belgelenmiş ve smoke testten geçmiştir.
+- Supabase, PWA/Dexie ve Poyraz UI v2 legacy kodu runtime'dan kaldırılmıştır.
+- Gelecekteki mobil istemci için service ve API sınırları belgelenmiştir.
+
+## 25. İlk uygulanacak çalışma paketi
+
+Plan onaylandıktan sonra önerilen ilk çalışma paketi:
+
+1. Bölüm 4'teki açık ürün kararlarını cevaplamak.
+2. ADR-0006'yı Poyraz UI v3 kararıyla değiştirmek.
+3. Tek owner/admin varsayımını schema ve authorization sözleşmesine yazmak.
+4. Hedef domain schema taslağını oluşturmak.
+5. Client invitation akışını tasarlamak.
+6. Poyraz UI v3 foundation için mevcut import/dependency envanterini çıkarmak.
+7. İlk sayfa grubu olarak kurulum, login, app shell ve branding/settings tasarımını netleştirmek.
diff --git a/docs/self-hosted-redesign/phase-0-adrs.md b/docs/self-hosted-redesign/phase-0-adrs.md
index 1f9aad0..8e4d52a 100644
--- a/docs/self-hosted-redesign/phase-0-adrs.md
+++ b/docs/self-hosted-redesign/phase-0-adrs.md
@@ -2,7 +2,7 @@
 title: Phase 0 ADR Set
 description: Self-hosted redesign için Faz 0'da kilitlenen mimari kararlar.
 status: active
-last_updated: 2026-07-10
+last_updated: 2026-07-16
 ---
 
 # Phase 0 ADR Set
@@ -93,20 +93,29 @@ Gerekçe:
 - S3 veya Supabase Storage self-host kurulumunu ağırlaştırır.
 - Tek volume backup modeli basit kalır.
 
-## ADR-0006: Internal Neta UI
+## ADR-0006: Poyraz UI v3 tek UI sistemi
 
 Status: Accepted for redesign baseline.
 
 Karar:
 
-- `poyraz-ui` runtime bağımlılığı kaldırılacak.
-- Neta'nın kendi `components/ui` primitive'leri ve semantic CSS token'ları kullanılacak.
-- Dialog, select, menu, tabs gibi davranışlı bileşenlerde tek bir headless primitive katmanı izole edilebilir.
+- Neta'nın genel UI atom, molecule ve organism katmanı `poyraz-ui@3` üzerinden kurulacak.
+- Paket kullanımı ana dağıtım modeli olacak; source registry yalnızca component source ownership gerektiren istisnalarda kullanılacak.
+- Button, form field, dialog, select, dropdown, tabs, sheet, sidebar, data table ve toast gibi genel primitive/davranışlar ikinci kez yazılmayacak.
+- `ProjectCard`, `ClientPipeline` ve `FinanceSummary` gibi Neta'ya özgü domain bileşenleri Poyraz UI componentlerinin kompozisyonu olarak yazılabilir.
+- Global CSS `poyraz-ui/preset.css` ve semantic token sistemini kullanacak.
+- Faz 3'te eklenmiş internal primitive ve shell'ler geçiş yüzeyidir; Poyraz UI v3 karşılığına taşındıktan sonra duplicate olanlar kaldırılacak.
 
 Gerekçe:
 
-- UI bağımlılığı self-host dağıtım ve uzun vadeli bakım riskini artırıyor.
-- Ürün UX'i freelancer workflow'una göre yeniden tasarlanacak.
+- Poyraz UI proje sahibinin kontrolündedir ve v3; Tailwind CSS v4, semantic theme tokenları, erişilebilir Radix davranışları ve app-level organisms sunar.
+- Tek paket altında primitive tekrarını azaltmak dependency sadeleştirme hedefiyle uyumludur.
+- Merkezi paket versiyonu Neta ile Poyraz UI arasındaki tasarım sözleşmesini görünür ve güncellenebilir tutar.
+
+Supersedes:
+
+- 2026-07-10 tarihli “Internal Neta UI” yönü geçersizdir.
+- `docs/self-hosted-redesign/phase-3-ui.md` tarihsel uygulama notu olarak korunur; ileriye dönük UI kararı değildir.
 
 ## ADR-0007: PWA/offline sync ilk release kapsam dışı
 
@@ -193,3 +202,80 @@ Gerekçe:
 
 - Persistent local volume ve single long-running Node process gereksinimi var.
 
+## ADR-0013: Tek owner/admin, birden fazla client
+
+Status: Accepted for self-hosted v3 first release.
+
+Karar:
+
+- Bir Neta instance'ı ilk sürümde tek aktif freelancer/owner hesabına sahip olacak.
+- Owner birden fazla client portal hesabı oluşturabilecek veya davet edebilecek.
+- İkinci freelancer, takım, organization ve workspace membership modeli ilk sürüm kapsamında olmayacak.
+- Domain tabloları yine de açık `owner_user_id` alanı taşıyacak; sabit bir global owner varsayımı repository filtrelerinin yerine geçmeyecek.
+
+Gerekçe:
+
+- İlk admin setup kilidi ve tek-instance SQLite hedefi mevcut ürün davranışıyla uyumludur.
+- Açık owner alanı import, authorization testi ve ileride kontrollü model genişletmesi için gereklidir.
+
+## ADR-0014: Supabase verisi için import uyumluluğu zorunlu
+
+Status: Accepted for self-hosted v3 first release.
+
+Karar:
+
+- Production veri miktarından bağımsız olarak mevcut Supabase modelinden SQLite'a tek seferlik import desteklenecek.
+- Auth password ve session verisi taşınmayacak; owner hesabı yeniden kurulacak, client kullanıcıları yeniden davet edilecek.
+- Import dry-run, satır sayımı, normalization raporu ve file checksum manifest'i üretecek.
+- Production dual-write yapılmayacak; cutover maintenance penceresinde gerçekleşecek.
+
+Gerekçe:
+
+- Uygulamanın halihazırdaki verisini kaybetmeden Supabase'ten çıkabilmesi ürün güvenilirliğinin parçasıdır.
+- Veri yoksa aynı araç fixture/import smoke amacıyla kullanılabilir.
+
+## ADR-0015: Business modülleri release-blocker değil
+
+Status: Accepted for self-hosted v3 first release.
+
+Karar:
+
+- Teklif, sözleşme, fatura ve abonelik kaynak verileri import kapsamında korunacak.
+- Bu modüllerin tam CRUD ve redesign işleri çekirdek müşteri/proje/görev/finans/portal akışlarını bloke etmeyecek.
+- Eksik business ekranları Faz 7'de tamamlanacak veya feature flag/navigation dışı bırakılacak.
+- Kaynak veri sessizce silinmeyecek; aktif hedef tabloya veya açıkça belgelenmiş archive modeline alınacak.
+
+Gerekçe:
+
+- Mevcut business ekranları kısmen read-only veya UI taslağı durumundadır.
+- Self-hosted çekirdeğin gecikmeden güvenli biçimde tamamlanması daha yüksek önceliktedir.
+
+## ADR-0016: İlk portal iletişimi proje görünürlüğü ve revizyonlarla sınırlı
+
+Status: Accepted for self-hosted v3 first release.
+
+Karar:
+
+- İlk release'te client iletişim yüzeyi proje durumu, public görevler, planlama bölümleri ve revizyon taleplerini kapsayacak.
+- Genel mesajlaşma, task comment thread'leri, notification merkezi ve e-posta entegrasyonu ilk release kapsamı dışında olacak.
+- Revizyon oluşturma project-client ilişkisini ve kotayı aynı server-side transaction içinde doğrulayacak.
+
+Gerekçe:
+
+- Mevcut portalın doğrulanabilir ürün davranışı bu kapsamdır.
+- Genel mesajlaşma ayrı notification, unread state, retention ve abuse kararları gerektirir.
+
+## ADR-0017: Web ve gelecek mobil istemci ortak service katmanını kullanır
+
+Status: Accepted for self-hosted v3 baseline.
+
+Karar:
+
+- Server Components ve Server Actions iş mantığını ortak service/repository katmanından çağıracak.
+- Gelecekteki `/api/v1` Route Handler'ları aynı service katmanına adapter olacak.
+- Web uygulaması kendi Route Handler'larına internal HTTP çağrısı yapmayacak.
+- Service katmanı `Request`, cookie veya Next.js navigation objelerine doğrudan bağımlı olmayacak.
+
+Gerekçe:
+
+- Web SSR performansını korurken React Native için tekrar kullanılabilir backend sınırı sağlar.
diff --git a/docs/self-hosted-redesign/phase-0-baseline.md b/docs/self-hosted-redesign/phase-0-baseline.md
index ba38911..2035f76 100644
--- a/docs/self-hosted-redesign/phase-0-baseline.md
+++ b/docs/self-hosted-redesign/phase-0-baseline.md
@@ -1,309 +1,401 @@
 ---
-title: Phase 0 Baseline
-description: Supabase ve Poyraz UI ayrımı başlamadan önce mevcut Neta uygulamasının repo, davranış, bağımlılık ve risk baseline'ı.
+title: Phase 0 v3 Baseline
+description: Supabase çıkışı ve Poyraz UI v3 dönüşümü başlamadan önce güncel repo, route, davranış, dependency ve doğrulama baseline'ı.
 status: active
-last_updated: 2026-07-10
+last_updated: 2026-07-16
 ---
 
-# Phase 0 Baseline
+# Phase 0 v3 Baseline
 
-Bu dosya, self-hosted redesign başlamadan önce repo üzerinden doğrulanabilen mevcut durumu sabitler. Production Supabase verisine erişim gerektiren satır sayıları, storage boyutları, gerçek kullanıcı akışı ekran kayıtları ve backup doğrulaması bu dokümanda tamamlanmış sayılmaz; bunlar `phase-0-data-mapping.md` içindeki production audit sorguları ve checklist istisnalarıyla takip edilir.
+Bu belge `neta-self-hosted-v3-master-plan.md` için Faz 0 kanıtıdır. Önceki 2026-07-10 baseline'ı; Better Auth, SQLite runtime, Docker ve yeni shell eklenmeden önceki durumu anlattığı için bu içerikle güncellenmiştir.
 
-## Kanıt komutları
+## 1. İnceleme kapsamı
 
-Bu baseline aşağıdaki local komutlarla oluşturuldu:
+İncelenen alanlar:
 
-```powershell
-git status --short
-rg --files
-rg --files .\app
-rg -n 'supabase|poyraz-ui|createClient|service_role|serviceRole|NEXT_PUBLIC_SUPABASE|from\(' app components lib config hooks --glob '*.ts' --glob '*.tsx'
-rg -n 'poyraz-ui' app components --glob '*.ts' --glob '*.tsx'
-rg -n 'create table if not exists public\.|create table if not exists neta_internal\.|alter table public\..*enable row level security|create policy|create or replace function|create index if not exists|create trigger|insert into storage\.buckets' supabase\migrations supabase\schema.sql
-rg -n 'select\("\*"\)|select\(''\*''\)|order_index|sort_order|completed|done|\.limit\(|\.range\(|useTransition|useOptimistic|startTransition|isPending|pending' app lib components --glob '*.ts' --glob '*.tsx'
+- Next.js route, layout, loading ve action yüzeyi
+- Better Auth ve SQLite runtime
+- Supabase browser/server/service-role kullanımları
+- Supabase kaynak schema, RLS, RPC ve storage kapsamı
+- Poyraz UI ve local UI component sınırı
+- Dependency kullanımı
+- Kritik freelancer ve client portal akışları
+- Typecheck, lint, build ve smoke script sonuçları
+
+İnceleme dalı ve commit:
+
+```text
+branch: codex-self-hosted-redesign-faz2
+HEAD: f5d89e8
 ```
 
-## Repo durumu
+## 2. Sayısal repo baseline'ı
 
-- Next.js App Router kullanılıyor.
-- Ayrı backend uygulaması yok; server davranışı `app` altındaki Server Components, Server Actions ve Route Handlers içinde.
-- Supabase şu anda auth, session refresh, RLS ile authorization, Postgres schema, RPC aggregate, storage ve service-role tabanlı kullanıcı/dosya işlemlerini taşıyor.
-- Poyraz UI uygulama shell, auth, dashboard, portal ve loading ekranlarına yayılmış durumda.
-- Dockerfile, Compose, migration runner, backup/restore script'i ve test harness yok.
-- `package.json` içinde `typecheck` veya test script'i yok; typecheck local TypeScript binary ile çalıştırılmalı.
-- Doküman olarak Faz 0 başlangıcında eklenmiş dosyalar: `docs/18-self-hosted-redesign-plani.md`, `docs/19-self-hosted-redesign-checklist.md`.
+| Ölçüm | Güncel değer |
+| --- | ---: |
+| Uygulama sayfası (`page.tsx`) | 22 |
+| Layout | 3 |
+| Route Handler | 8 |
+| Server Action dosyası | 10 |
+| Export edilen async Server Action | 33 |
+| Loading boundary | 6 |
+| Client Component | 40 |
+| Uygulama/server/script TS/TSX/MJS satırı | yaklaşık 16.014 |
+| Poyraz UI import eden app/component dosyası | 26 |
+| Supabase entegrasyonu içeren app/lib/server dosyası | 40 |
+| Browser Supabase client kullanan ekran | 2 |
+| Production dependency | 47 |
+| Dev dependency | 12 |
+| Supabase kaynak tablo | 20; 19 ürün/public + 1 internal |
+| Supabase storage bucket | 2 |
+| Mevcut SQLite tablo | 10; auth/setup/audit/runtime |
 
-## Route envanteri
+## 3. Güncel çalışma zamanı
 
-Route group'lar:
+Repo artık iki mimariyi aynı anda içeriyor.
 
-- `(dashboard)`: freelancer dashboard, core OS ekranları ve business ekranları.
-- `portal`: client portal.
-- `api`: AI, health ve internal route handler'ları.
-- Top-level auth: `login`, `register`.
+### Yeni self-hosted temel
 
-Sayfa/layout/loading/action dosyaları:
+- Better Auth email/password ve DB session
+- `better-sqlite3`
+- Drizzle schema ve migration
+- İlk freelancer setup lock'u
+- `app_profiles`
+- Portal invitation tablo iskeleti
+- Auth audit events
+- SQLite WAL/foreign key/busy timeout ayarları
+- Health live/ready endpoint'leri
+- Migration, backup ve restore script'leri
+- Next.js standalone Dockerfile
+- Tek persistent volume kullanan Compose tanımı
 
-| Dosya | Rol |
-| --- | --- |
-| `app/layout.tsx` | Root layout, manifest, global toaster |
-| `app/login/page.tsx` | Login ekranı |
-| `app/login/actions.ts` | Login, signup, sign out Server Actions |
-| `app/register/page.tsx` | İlk admin/freelancer setup ekranı |
-| `app/(dashboard)/layout.tsx` | Dashboard auth guard ve shell |
-| `app/(dashboard)/page.tsx` | Dashboard Server Component |
-| `app/(dashboard)/dashboard-client.tsx` | Dashboard client UI |
-| `app/(dashboard)/loading.tsx` | Dashboard loading skeleton |
-| `app/(dashboard)/analytics/page.tsx` | Analytics Server Component |
-| `app/(dashboard)/analytics/analytics-client.tsx` | Analytics client UI |
-| `app/(dashboard)/analytics/loading.tsx` | Analytics loading skeleton |
-| `app/(dashboard)/business/invoices/page.tsx` | Invoices Server Component |
-| `app/(dashboard)/business/invoices/invoices-client.tsx` | Invoices client UI |
-| `app/(dashboard)/business/proposals/page.tsx` | Proposals Server Component |
-| `app/(dashboard)/business/proposals/proposals-client.tsx` | Proposals client UI |
-| `app/(dashboard)/business/subscriptions/page.tsx` | Subscriptions Server Component |
-| `app/(dashboard)/business/subscriptions/subscriptions-client.tsx` | Subscriptions client UI |
-| `app/(dashboard)/calendar/page.tsx` | Calendar Server Component |
-| `app/(dashboard)/calendar/calendar-client.tsx` | Calendar client UI |
-| `app/(dashboard)/calendar/actions.ts` | Calendar mutation Server Actions |
-| `app/(dashboard)/chat/page.tsx` | AI chat client-heavy screen |
-| `app/(dashboard)/clients/page.tsx` | Clients Server Component |
-| `app/(dashboard)/clients/clients-client.tsx` | Clients client UI |
-| `app/(dashboard)/clients/actions.ts` | Client mutation Server Actions |
-| `app/(dashboard)/clients/loading.tsx` | Clients loading skeleton |
-| `app/(dashboard)/clients/[id]/page.tsx` | Client detail Server Component |
-| `app/(dashboard)/clients/[id]/client-detail-client.tsx` | Client detail client UI |
-| `app/(dashboard)/clients/[id]/actions.ts` | Client activity mutation Server Actions |
-| `app/(dashboard)/finance/page.tsx` | Finance Server Component |
-| `app/(dashboard)/finance/finance-client.tsx` | Finance client UI |
-| `app/(dashboard)/finance/actions.ts` | Finance mutation Server Actions |
-| `app/(dashboard)/journal/page.tsx` | Daily log Server Component |
-| `app/(dashboard)/journal/journal-client.tsx` | Daily log client UI |
-| `app/(dashboard)/journal/actions.ts` | Daily log mutation Server Actions |
-| `app/(dashboard)/projects/page.tsx` | Projects Server Component |
-| `app/(dashboard)/projects/projects-client.tsx` | Projects client UI |
-| `app/(dashboard)/projects/actions.ts` | Project/planning/revision mutation Server Actions |
-| `app/(dashboard)/projects/loading.tsx` | Projects loading skeleton |
-| `app/(dashboard)/projects/[id]/page.tsx` | Project detail Server Component |
-| `app/(dashboard)/projects/[id]/project-detail-client.tsx` | Project detail client UI |
-| `app/(dashboard)/projects/[id]/loading.tsx` | Project detail loading skeleton |
-| `app/(dashboard)/settings/page.tsx` | Settings client screen |
-| `app/(dashboard)/settings/actions.ts` | Profile/password mutation Server Actions |
-| `app/(dashboard)/tasks/page.tsx` | Tasks Server Component |
-| `app/(dashboard)/tasks/tasks-client.tsx` | Tasks kanban/client UI |
-| `app/(dashboard)/tasks/actions.ts` | Task mutation Server Actions |
-| `app/(dashboard)/tasks/loading.tsx` | Tasks loading skeleton |
-| `app/portal/layout.tsx` | Client portal auth guard and shell |
-| `app/portal/page.tsx` | Portal home |
-| `app/portal/projects/page.tsx` | Portal projects list |
-| `app/portal/projects/[id]/page.tsx` | Portal project detail Server Component |
-| `app/portal/projects/[id]/portal-project-client.tsx` | Portal project detail client UI |
-| `app/portal/projects/[id]/actions.ts` | Portal revision Server Action |
-| `app/portal/revisions/page.tsx` | Portal revisions list |
-| `app/portal/tasks/page.tsx` | Portal tasks list |
+### Henüz taşınmamış feature runtime
 
-Route Handlers:
+- Müşteriler
+- Client activities
+- Projeler ve planning sections
+- Görevler
+- Takvim
+- Finans
+- Günlük
+- Analytics/dashboard RPC
+- Chat session/message
+- AI settings/context
+- Client portal verileri ve revision mutation
+- Avatar ve project asset storage
 
-| Route | Dosya | Mevcut sorumluluk |
+Bu feature'lar hâlâ Supabase Auth principal'ı, Postgres, RLS ve Storage bekliyor.
+
+## 4. Kritik hibrit-auth baseline'ı
+
+Dashboard ve portal layout'ları Better Auth session kullanıyor:
+
+- `app/(dashboard)/layout.tsx` → `requireFreelancer()`
+- `app/portal/layout.tsx` → `requireClientUser()`
+
+Alt feature sayfaları ve action'lar ise Supabase `auth.getUser()` kullanıyor. Better Auth cookie'si Supabase session üretmediği için güncel dal uçtan uca çalışan tek auth sistemi sunmuyor.
+
+Beklenen mevcut sonuç:
+
+- Better Auth ile giriş yapan freelancer layout guard'ını geçebilir.
+- Aynı kullanıcı Supabase tabanlı page/action içinde oturumsuz görünür.
+- Feature reads/mutations boş sonuç, redirect, `null` veya auth hatası verebilir.
+- Better Auth client profile oluşturacak invitation consume akışı henüz yoktur.
+- Eski `/api/create-client-user` route'u Supabase Auth user üretir ve yeni portal layout'ının beklediği SQLite profile'ı üretmez.
+
+Bu durum redesign sırasında korunacak davranış değil, ortadan kaldırılması gereken geçiş kırığıdır.
+
+## 5. Route ve özellik envanteri
+
+### 5.1. Auth ve platform
+
+| Route | Durum | Not |
 | --- | --- | --- |
-| `POST /api/chat` | `app/api/chat/route.ts` | Chat message persistence, settings read, AI response |
-| `POST /api/create-client-user` | `app/api/create-client-user/route.ts` | Freelancer'ın client auth user oluşturması |
-| `POST /api/finance-analysis` | `app/api/finance-analysis/route.ts` | Finance transactions üzerinden AI analiz |
-| `GET /api/health` | `app/api/health/route.ts` | Basic liveness JSON |
-| `POST /api/project-risk` | `app/api/project-risk/route.ts` | Project/tasks üzerinden AI risk analizi |
+| `/login` | Var | Better Auth Server Action kullanıyor |
+| `/register` | Var | İlk freelancer setup akışı |
+| `/forgot-password` | Yok | Login ekranında link var; gerçek route/akış yok |
+| `/api/auth/[...all]` | Var | Better Auth handler |
+| `/api/health` | Var | Edge basic health |
+| `/api/health/live` | Var | Process liveness |
+| `/api/health/ready` | Var | SQLite/data dir/migration readiness |
 
-## Supabase kullanım envanteri
+### 5.2. Freelancer ekranları
 
-Browser Supabase client kullanan dosyalar:
+| Route | Mevcut yetenek | Veri kaynağı | v3 kararı |
+| --- | --- | --- | --- |
+| `/` | KPI, trend, recent project/client | Supabase RPC + tables | Aggregate repository |
+| `/analytics` | Dönemsel finans/görev analizi | Supabase RPC | SQLite aggregate repository |
+| `/clients` | Liste, filtre, pipeline, CRUD | Supabase | İlk core vertical slice |
+| `/clients/[id]` | Detay ve activity timeline | Supabase | Owner-filtered service |
+| `/projects` | Liste, filtre, CRUD, cover | Supabase + Storage | Local file metadata |
+| `/projects/[id]` | Planning, tasks, finance, revisions | Supabase + Storage | Transaction/service sınırı |
+| `/tasks` | Liste/kanban, CRUD, status | Supabase | Task/project transaction |
+| `/calendar` | Event CRUD | Supabase | Visible-range query |
+| `/finance` | Income/expense CRUD | Supabase | Integer minor unit |
+| `/journal` | Daily log CRUD | Supabase `daily_logs` | `journal_entries` |
+| `/chat` | AI session/message UI | Browser Supabase + API | Server-only chat service |
+| `/settings` | Profil, avatar, AI key, password | Browser/server Supabase | Better Auth + settings service |
 
-- `app/(dashboard)/chat/page.tsx`: session/message CRUD ve `auth.getUser`.
-- `app/(dashboard)/settings/page.tsx`: profile/settings read ve `app_settings` upsert.
-- `lib/supabase/client.ts`: `createBrowserClient` factory.
+### 5.3. Business ekranları
 
-Server Supabase client kullanan başlıca dosyalar:
-
-- Auth/setup: `app/login/actions.ts`, `app/register/page.tsx`, `lib/auth/first-admin-setup.ts`, `lib/supabase/server.ts`, `lib/supabase/middleware.ts`.
-- Dashboard reads: `app/(dashboard)/page.tsx`, `analytics/page.tsx`, `clients/page.tsx`, `clients/[id]/page.tsx`, `projects/page.tsx`, `projects/[id]/page.tsx`, `tasks/page.tsx`, `calendar/page.tsx`, `finance/page.tsx`, `journal/page.tsx`, business pages.
-- Dashboard mutations: `clients/actions.ts`, `clients/[id]/actions.ts`, `projects/actions.ts`, `tasks/actions.ts`, `calendar/actions.ts`, `finance/actions.ts`, `journal/actions.ts`, `settings/actions.ts`.
-- Portal reads/mutations: `app/portal/**/*.tsx`, `app/portal/projects/[id]/actions.ts`.
-- AI/routes: `app/api/chat/route.ts`, `app/api/finance-analysis/route.ts`, `app/api/project-risk/route.ts`, `lib/ai/embeddings.ts`.
-
-Service-role kullanımı:
-
-- `lib/supabase/admin.ts`: `SUPABASE_SERVICE_ROLE_KEY` ile admin client.
-- `lib/auth/internal-users.ts`: `request_internal_auth_creation` RPC ve Supabase Admin `auth.admin.createUser`.
-- `app/api/create-client-user/route.ts`: internal user creation flow.
-- `app/(dashboard)/projects/actions.ts`: `project-assets` upload için service-role client.
-- `app/(dashboard)/projects/page.tsx` ve `app/(dashboard)/projects/[id]/page.tsx`: project-assets public URL/asset erişim path'i.
-- `app/(dashboard)/settings/actions.ts`: avatars upload ve public URL üretimi.
-
-RPC kullanımı:
-
-- `is_first_admin_setup_available`: first admin setup guard.
-- `request_internal_auth_creation`: service-role guard ile internal user creation.
-- `match_documents`: pgvector similarity search.
-- `get_dashboard_metrics`: dashboard aggregate.
-- `get_analytics_metrics`: analytics aggregate.
-
-Storage kullanımı:
-
-- `avatars`: public avatar URL'leri; settings flow.
-- `project-assets`: private project cover/assets; path convention user id folder'ı üzerinden.
-
-## Poyraz UI import envanteri
-
-Poyraz UI kullanılan dosya sayısı: 36 uygulama/component dosyası.
-
-Kullanılan namespace'ler:
-
-- `poyraz-ui/atoms`: `Badge`, `Button`, `Card`, `CardContent`, `Input`, `Label`, `Textarea`, `Typography`.
-- `poyraz-ui/molecules`: `Dialog*`, `DropdownMenu*`, `Select*`, `Tabs*`, `toast`, `Toaster`.
-- `poyraz-ui/organisms`: dashboard ve portal shell navigation bileşenleri.
-
-Yoğun kullanım alanları:
-
-- Layout shell: `components/layout/dashboard-shell.tsx`, `components/layout/portal-shell.tsx`.
-- Auth: `components/auth/*`, `app/login/page.tsx`, `app/register/page.tsx`.
-- Dashboard features: clients, projects, tasks, calendar, finance, journal, analytics, business.
-- Portal: portal home, projects, tasks, revisions.
-- Loading states: birden fazla loading skeleton dosyası Poyraz `Card`/`CardContent` kullanıyor.
-
-Replacement yönü:
-
-- Atoms doğrudan `components/ui` primitive'lerine taşınacak.
-- Molecules içindeki dialog/select/dropdown/tabs gibi davranışlı bileşenler tek internal UI katmanında izole edilecek.
-- Organisms shell'leri Faz 3'te Neta shell olarak yeniden yazılacak.
-- `toast`/`Toaster` tek internal feedback API'sine taşınacak.
-
-## Internal UI durumu
-
-Mevcut `components/ui` dizininde şu bileşenler var:
-
-- Aktif internal primitive adayları: `button.tsx`, `card.tsx`, `checkbox.tsx`, `dialog.tsx`, `dropdown-menu.tsx`, `form.tsx`, `icon.tsx`, `input.tsx`, `label.tsx`, `select.tsx`, `separator.tsx`, `skeleton.tsx`, `textarea.tsx`, `toast.tsx`, `toaster.tsx`.
-- Geçiş yardımcıları: `pending-link.tsx`, `pending-submit-button.tsx`, `offline-indicator.tsx`.
-- Not: `components/ui/pending-submit-button.tsx` hâlâ `poyraz-ui/atoms` `Button` import ediyor; UI katmanı tamamen bağımsız değil.
-
-## Dexie/IndexedDB ve PWA baseline
-
-Dexie:
-
-- `lib/db.ts` içinde IndexedDB prototipi var.
-- `rg` sonucunda aktif app import'u görünmüyor.
-- Tip düzeyi eski task status değeri `completed` içeriyor; yeni task kanoniğiyle uyumsuz.
-- Hedef redesign'da kaldırılacak veya Faz 0 sonrası ayrı bir cleanup commit'inde silinecek.
-
-PWA:
-
-- `next.config.ts` içinde `@ducanh2912/next-pwa` aktif.
-- Production build'de `public` altına service worker asset'leri üretmesi beklenir.
-- `app/layout.tsx` manifest olarak `/manifest.json` tanımlıyor.
-- Offline-first veri sync hedef dışı olduğu için ilk self-hosted release'te PWA kaldırma kararı ADR'de sabitlenmiştir.
-
-## Dependency sınıflandırması
-
-Kalacak:
-
-- `next`, `react`, `react-dom`, `typescript`, `eslint`, `eslint-config-next`
-- `zod`, `react-hook-form`, `@hookform/resolvers`
-- `date-fns`, `clsx`, `tailwind-merge`
-- `lucide-react`
-- AI provider paketleri, yalnızca server tarafına izole edilmek şartıyla
-
-Kaldırılacak:
-
-- `@supabase/ssr`, `@supabase/supabase-js`: runtime Supabase bağımlılığı kaldırılacak.
-- `poyraz-ui`: internal UI ile değiştirilecek.
-- `dexie`, `dexie-react-hooks`: aktif akışta kullanılmıyor.
-- `@ducanh2912/next-pwa`: ilk self-hosted release'te offline/PWA kapsam dışı.
-- `shadcn`: runtime ihtiyacı yoksa kaldırılacak.
-- Duplicate/unused Radix veya umbrella `radix-ui` paketleri, internal UI kararından sonra temizlenecek.
-
-Değerlendirilecek:
-
-- `@base-ui/react`: tek headless primitive katmanı olarak kalabilir veya Radix ile karşılaştırılıp kaldırılabilir.
-- `@radix-ui/*`: internal UI behavior için seçilecek tek headless katmana göre azaltılacak.
-- `framer-motion`: kritik UX değeri yoksa kaldırılacak; varsa reduced-motion standardıyla izole edilecek.
-- `recharts`: analytics UI redesign kapsamına göre kalabilir.
-- `@iconify/react`: lucide-react yeterliyse kaldırılacak.
-- `tailwindcss-animate`: animasyon stratejisine göre değerlendirilecek.
-- `uuid` ve `@types/uuid`: Web Crypto UUID yeterliyse kaldırılacak.
-
-## Davranış baseline matrisi
-
-Bu davranışlar yeni sistemde korunacak veya bilinçli olarak iyileştirilecek:
-
-| Akış | Mevcut davranış | Redesign notu |
+| Route | Güncel durum | İlk release kararı |
 | --- | --- | --- |
-| İlk admin setup | `/register`, `is_first_admin_setup_available`, signup sonrası profile role `freelancer` | Better Auth setup route'u public registration'ı ilk kullanıcıdan sonra kapatacak |
-| Login/logout | Supabase `signInWithPassword`, `signOut`, middleware session refresh | Better Auth DB session ve server-side session helper |
-| Client portal hesabı | Freelancer route handler üzerinden client auth user yaratıyor | Invite token ve client self-activation tercih edilecek |
-| Client CRUD | Server Actions + Supabase RLS | Service/repository owner filter |
-| Project CRUD | Server Actions, cover image storage, planning sections | Local storage metadata + transaction boundary |
-| Task kanban | Client optimistic-ish state, Server Actions, `done` kanoniği | Transaction içinde auto progress ve rollback testleri |
-| Calendar | Server read + Server Actions | Visible range/pagination zorunlu |
-| Finance | Server read + Server Actions, decimal amount | Minor unit integer standardı |
-| Business docs | Page-level read-only/dummy-ish client UIs | Faz 5'te gerçek mutation ve constraints gözden geçirilecek |
-| Journal | `daily_logs` aktif; `journals` legacy | `journal_entries` kanonik hedef |
-| Analytics/dashboard | Supabase RPC aggregate | Drizzle/SQL aggregate repository |
-| AI chat | Browser Supabase client + `/api/chat` route | Browser DB erişimi kaldırılacak |
-| Settings/profile | Browser Supabase client + Server Action mix | Server-only settings service |
-| Portal revisions | UI warning var, server quota enforcement eksik | Server action quota ve ownership negatif test |
+| `/business/proposals` | Read + ekleme dialog taslağı; gerçek mutation yok | Release-blocker değil |
+| `/business/invoices` | Read + ekleme dialog taslağı; gerçek mutation yok | Release-blocker değil |
+| `/business/subscriptions` | Read + ekleme dialog taslağı; gerçek mutation yok | Release-blocker değil |
+| Contracts | Kaynak tablo var; sayfa yok | Release-blocker değil |
 
-## Bilinen problem baseline
+Kaynak veriler import sırasında korunacak; eksik UI/CRUD Faz 7'ye bırakılacak veya navigation dışı tutulacak.
 
-Regression maddesine çevrilecek mevcut problemler:
+### 5.4. Client portal
 
-- Portal project detail `project_planning_sections` için `order_index` ile order ediyor; schema alanı `sort_order`.
-- Project risk route `completed` task status sayıyor; aktif kanonik status `done`.
-- Portal project client UI section tipi olarak `type` okuyor; schema alanı `category`.
-- Revision quota sadece UI tarafında uyarı olarak var; server action `createRevisionRequest` quota uygulamıyor.
-- Portal revision insert policy project/client eşleşmesini tam doğrulamıyor; client kendi `client_id` değeriyle başka projeye request deneyebilir.
-- `app/(dashboard)/chat/page.tsx` ve `app/(dashboard)/settings/page.tsx` browser Supabase client ile auth/veri erişimi yapıyor.
-- Bazı listeler pagination yerine tüm kullanıcı datasını veya geniş tarih aralığını çekiyor.
-- AI API key `app_settings.api_key` içinde düz metin tutuluyor ve settings client'ına geri okunuyor.
-
-## Performans baseline
-
-Local static baseline:
-
-- Dashboard ve analytics aggregate RPC ile payload azaltılmış; ancak bazı detail/list sayfalarında birden fazla Supabase query paralel çalışıyor.
-- Client JS yüzeyi ağır: Poyraz UI, motion, charts, AI chat, kanban ve portal client bileşenleri geniş kullanımda.
-- `app/api/chat/route.ts` kullanıcı context'i için `tasks`, `projects`, `finance_transactions`, `daily_logs` sorgularında explicit `.limit()` kullanıyor.
-- `app/(dashboard)/journal/page.tsx` 180 kayıt limiti kullanıyor.
-- `app/(dashboard)/page.tsx` recent projects/clients için 5 kayıt limiti kullanıyor.
-- Calendar visible range filtresi yerine current implementation daha geniş veri çekme riski taşıyor; Faz 4'te görünür aralık zorunlu olacak.
-
-Ölçülmemiş production baseline:
-
-- Gerçek TTFB, payload boyutu, route client JS boyutu ve click-to-feedback metrikleri production veya seeded local environment ayağa kaldırılmadan tamamlanmış sayılmaz.
-- Bu metrikler Faz 1 spike container'ı ve import rehearsal sonrası tekrar ölçülecek.
-
-## Local doğrulama sonuçları
-
-2026-07-10 local workspace sonuçları:
-
-| Komut | Sonuç | Not |
+| Route | Güncel yetenek | Bilinen sınır |
 | --- | --- | --- |
-| `npm.cmd run lint` | Başarısız | 34 error, 25 warning. Mevcut baseline: `any`, React `setState-in-effect`, unused import, unescaped entities, `<img>` warnings. Faz 0 doküman değişiklikleri app code değiştirmedi. |
-| `.\node_modules\.bin\tsc.cmd --noEmit` | Başarılı | TypeScript typecheck temiz. |
-| `npm.cmd run build` | Başarılı | Next.js 16.2.7 Turbopack production build geçti. Edge runtime static generation warning'i mevcut build uyarısı olarak görüldü. |
+| `/portal` | Proje KPI ve proje kartları | Hybrid auth nedeniyle veri session'ı kırık |
+| `/portal/projects` | Client'a bağlı projeler | Supabase RLS'e bağlı |
+| `/portal/projects/[id]` | Progress, public tasks, planning, revisions | `order_index`/`sort_order` uyumsuzluğu |
+| `/portal/tasks` | Public görevler | Eski `completed` toleransı var |
+| `/portal/revisions` | Revision geçmişi | Genel mesajlaşma yok |
+| `/portal/settings` | Yok | Shell hesap menüsü bu route'a link üretiyor |
 
-Local environment:
+### 5.5. AI ve internal API
 
-- Node: `v24.11.1`
-- npm: `11.6.2`
-- CPU identifier: `Intel64 Family 6 Model 167 Stepping 1, GenuineIntel`
-- Logical processor count: `16`
-- Disk root: `D:\`
-- RAM: WMI/CIM erişimi sandbox içinde reddedildiği için ölçülemedi.
+| Route | Sorumluluk | v3 riski/kararı |
+| --- | --- | --- |
+| `POST /api/chat` | Context oluşturma ve streaming chat | Supabase session/data ve client-supplied key |
+| `POST /api/finance-analysis` | Son 30 gün finance analizi | Supabase ve düz metin API key |
+| `POST /api/project-risk` | Project/task risk analizi | Owner filter RLS'e bırakılmış; `completed` uyumsuzluğu |
+| `POST /api/create-client-user` | Supabase client auth user üretme | Better Auth invitation ile kaldırılacak |
 
-## Faz 0 istisnaları
+## 6. Kritik kullanıcı akışı baseline'ı
 
-Production erişimi gerektiren ve bu local çalışmada tamamlanmayan kalemler:
+| Akış | Kodda mevcut davranış | v3'te korunacak/iyileştirilecek sözleşme |
+| --- | --- | --- |
+| İlk admin setup | Atomic Better Auth setup lock ve freelancer profile | Korunacak; smoke/negative test eklenecek |
+| Login/logout | Better Auth Server Actions | Korunacak; forgot-password eklenecek |
+| Client hesabı | Eski Supabase admin route'u + yeni invitation tablo iskeleti | Süreli hash token ile self-activation |
+| Client CRUD | Supabase Server Actions ve RLS | Repository owner filter |
+| Project CRUD | Supabase actions, planning ve storage | Service + local file transaction sınırı |
+| Task kanban | Client state + Supabase action; `done` kanoniği | Task update ve auto progress aynı transaction |
+| Calendar | Tüm/ geniş event datası | Visible date range zorunlu |
+| Finance | Decimal amount | Integer minor unit |
+| Journal | `daily_logs` aktif, `journals` legacy | Tek `journal_entries` modeli |
+| Dashboard/analytics | Supabase RPC | SQLite aggregate repository |
+| Settings | Browser Supabase + localStorage API key | Server-only settings; secret browser'a dönmez |
+| Portal project | RLS ile client project read | Actor/client/project explicit ilişki kontrolü |
+| Portal revision | UI quota uyarısı, zayıf insert policy | Kota ve ilişki aynı transaction içinde |
+| AI chat | Kullanıcı verisi cloud provider'a gönderiliyor | Açık gizlilik bildirimi ve server-only secret |
 
-- Production Supabase backup alma ve restore doğrulama.
-- Production tablo/status dağılımlarını sayma.
-- Storage bucket dosya sayısı, toplam boyut ve orphan path raporu.
-- Gerçek kullanıcı akışı ekran kayıtları.
-- Gerçek route timing, payload ve bundle ölçümleri.
-- Ürün sahibi onayı gereken ADR ve kritik akış matrisi.
+Bu tablo Faz 0 kritik davranış kaydıdır. Canlı ekran kaydı mevcut hibrit auth nedeniyle güvenilir parity kanıtı sayılmayacaktır; vertical slice kabulünde yeni ekran kayıtları alınacaktır.
+
+## 7. Supabase kaynak envanteri
+
+`supabase/setup.sql` üzerinden doğrulanan kaynak tablolar:
+
+```text
+profiles
+clients
+client_activities
+projects
+project_planning_sections
+project_revisions
+tasks
+calendar_events
+finance_transactions
+daily_logs
+journals
+app_settings
+proposals
+contracts
+invoices
+subscriptions
+chat_sessions
+chat_messages
+document_embeddings
+neta_internal.internal_auth_creations
+```
+
+Storage bucket'ları:
+
+- `avatars`
+- `project-assets`
+
+Kaynak RPC/trigger function yüzeyi:
+
+- `handle_new_user`
+- `set_updated_at`
+- `is_first_admin_setup_available`
+- `request_internal_auth_creation`
+- `neta_current_jwt_role`
+- `update_project_progress_on_task_change`
+- `update_project_progress_on_type_change`
+- `get_dashboard_metrics`
+- `get_analytics_metrics`
+- `match_documents`
+
+### 7.1. Fixture satır baseline'ı
+
+`supabase/seeds/0001_demo_freelancer_os_data.sql` deterministik içerik:
+
+| Tablo | Satır |
+| --- | ---: |
+| clients | 2 |
+| projects | 3 |
+| tasks | 3 |
+| calendar_events | 2 |
+| finance_transactions | 3 |
+| daily_logs | 3 |
+| app_settings | 1 |
+
+`supabase/seed.sql` legacy fixture; 1 profile, 1 settings, 2 project, 3 task, 3 finance ve 3 daily log içerir. Bu seed'de `completed` task status'ü ve `daily_logs.notes` alanı gibi güncel schema ile uyumsuz legacy değerler vardır; hedef seed olarak kullanılmayacaktır.
+
+### 7.2. Production veri sayımı durumu
+
+Workspace'te yalnızca `.env.example` vardır; read-only production Supabase bağlantısı veya export snapshot'ı bulunmamaktadır. Bu nedenle gerçek production satır sayıları, status dağılımları, bucket dosya sayıları/boyutları ve orphan path raporu ölçülmemiştir.
+
+Çalıştırılacak sorgular `phase-0-data-mapping.md` içinde hazırdır. Bu veri gelmeden ana plandaki “Supabase tablo ve storage veri sayıları çıkarıldı” maddesi işaretlenmez.
+
+## 8. Mevcut SQLite envanteri
+
+Mevcut tablolar:
+
+```text
+user
+session
+account
+verification
+app_profiles
+app_setup_state
+portal_invitations
+auth_audit_events
+runtime_checks
+runtime_events
+```
+
+Henüz domain tablosu yoktur. `portal_invitations` yalnızca schema düzeyindedir; davet oluşturma/kabul/revoke service ve route akışı uygulanmamıştır.
+
+## 9. Supabase kod bağımlılığı baseline'ı
+
+- 40 app/lib/server dosyası Supabase entegrasyonu veya helper'ı içeriyor.
+- 2 client ekran browser Supabase client kullanıyor: chat ve settings.
+- 33 feature page/action/route Supabase feature verisine doğrudan bağlı.
+- Service-role client avatar, project asset ve client auth user oluşturmak için kullanılıyor.
+- Dashboard/analytics iki RPC'ye bağlı.
+- Embedding helper `match_documents` pgvector RPC'sine bağlı.
+
+Supabase kaldırma ancak bu kullanımların tamamı service/repository/file katmanına taşındıktan sonra yapılacaktır.
+
+## 10. Poyraz UI v3 baseline'ı
+
+- Package manifest: `poyraz-ui@^2.1.0`
+- Hedef referans: `poyraz-ui@3.0.2`
+- Poyraz UI import eden dosya: 26
+- Import yüzeyi: atoms ve molecules; güncel custom shell Poyraz organism kullanmıyor.
+- `components/ui` altında 19 local primitive/helper dosyası var.
+- Faz 3 local shell/primitive yönü ADR-0006 tarafından supersede edilmiştir.
+- Hedef: generic UI için Poyraz UI v3; Neta domain componentleri Poyraz kompozisyonu.
+
+Poyraz v3 migration sırasında local primitive dosyaları hemen topluca silinmeyecek. Her kullanım taşındıktan ve import boundary doğrulandıktan sonra duplicate dosya/dependency kaldırılacak.
+
+## 11. Dependency baseline'ı
+
+Doğrudan production dependency sayısı 47'dir.
+
+Statik import taramasında aktif kullanımı bulunmayan adaylar:
+
+- `@base-ui/react`
+- `dexie-react-hooks`
+- `shadcn`
+- `uuid`
+
+Çok sınırlı kullanım:
+
+- `@iconify/react`: 1 dosya
+- `framer-motion`: 1 dosya
+- `next-themes`: 1 dosya
+
+Geçiş sonrasında kaldırılacak ana gruplar:
+
+- Supabase SDK'ları
+- PWA ve Dexie
+- Poyraz v3'ün gereksiz kıldığı direct Radix/Base UI/shadcn bağımlılıkları
+- Aktif importu olmayan yardımcı paketler
+
+Kanban için DnD Kit, grafikler için Recharts ve kullanılan AI provider paketleri işlevsel gerekçeyle korunabilir.
+
+## 12. Bilinen regression ve güvenlik baseline'ı
+
+- Portal planning query `order_index` kullanıyor; schema alanı `sort_order`.
+- Portal planning UI `section.type` okuyor; schema alanı `category`.
+- Project risk route `completed` sayıyor; kanonik task status `done`.
+- Revision quota yalnızca UI'da kontrol ediliyor.
+- Revision insert policy project-client eşleşmesini tam doğrulamıyor.
+- Settings AI API key'i DB'de düz metin, browser state ve `localStorage` içinde tutuyor.
+- Chat/settings browser Supabase SDK ile DB/auth erişimi yapıyor.
+- Project risk tek proje sorgusu açık owner predicate taşımıyor; güvenliği RLS'e bırakıyor.
+- Clients/projects/tasks/calendar/finance listelerinde genel pagination yok.
+- `/forgot-password` ve `/portal/settings` link hedefleri mevcut değil.
+- Business create dialog'ları gerçek mutation yapmıyor.
+- Veri sorgularının bir kısmı hatayı boş liste gibi gösteriyor.
+
+Bu maddeler `phase-0-regression-and-spike.md` içindeki regression backlog ile takip edilir.
+
+## 13. Performans baseline'ı
+
+- Dashboard recent project/client sorguları 5 kayıtla sınırlı.
+- Journal sorgusu 180 kayıtla sınırlı.
+- Chat context sorguları 12–20 kayıt arasında limit kullanıyor.
+- Diğer ana liste ekranlarında `.range()` pagination görülmüyor.
+- Dashboard ve analytics aggregate işlemleri Supabase RPC ile server-side yapılmış.
+- En büyük client dosyaları yaklaşık 500–1.260 satır aralığında; feature UI parçalama ihtiyacı var.
+- 40 Client Component ve duplicate UI runtime'ı client bundle riskini artırıyor.
+
+Gerçek TTFB, route payload ve client JS ölçümü mevcut hibrit auth ve eksik local feature schema nedeniyle güvenilir değildir; ilgili vertical slice tamamlandığında yeniden ölçülecektir.
+
+## 14. 2026-07-16 local doğrulama sonuçları
+
+Ortam:
+
+```text
+Node: v24.16.0
+pnpm: 11.5.1
+Platform: macOS arm64
+```
+
+| Komut | Sonuç | Kanıt/not |
+| --- | --- | --- |
+| `npm run typecheck` | Başarılı | TypeScript hata vermedi |
+| `npm run phase3:ui-boundary` | Başarılı | Tarihsel internal UI boundary script'i geçti |
+| `npm run lint` | Başarısız | 32 error, 22 warning; `any`, `set-state-in-effect`, unused import, unescaped entity ve image uyarıları |
+| `npm run phase1:smoke` | Başarısız | `better-sqlite3` native binding yok |
+| `npm run phase2:smoke` | Çalışmadı | Faz 1 zinciri başarısız olduğu için başlanmadı; aynı native runtime'a bağlı |
+| `npm run build` | Başarısız | Compile ve TypeScript geçti; page data aşamasında default `/app/data` oluşturulamadı |
+| Temp `DATA_DIR` ile build | Başarısız | `/app/data` sorunu izole edildi; sonra eksik `better-sqlite3` binding'inde durdu |
+
+Pnpm durumu:
+
+- `pnpm ignored-builds`, `better-sqlite3`, `esbuild`, `sharp` ve `unrs-resolver` build scriptlerinin ignore edildiğini raporluyor.
+- `pnpm-workspace.yaml` içindeki `allowBuilds` değerleri henüz boolean olarak kilitlenmemiş.
+- Native binding düzeltilmeden SQLite smoke ve production build yeşil kabul edilemez.
+- Build sırasında production varsayılanının `/app/data` olması builder aşamasında güvenli build-time path gereksinimi doğuruyor; Faz 1 hardening maddesidir.
+
+## 15. Faz 0 tamamlanma durumu
+
+Tamamlanan:
+
+- Ürün kapsam kararları ADR ile kilitlendi.
+- Güncel route ve özellik envanteri çıkarıldı.
+- Kritik kullanıcı akışları kod davranışı ve hedef sözleşmeyle kaydedildi.
+- Supabase kaynak schema, bucket, RPC ve fixture envanteri çıkarıldı.
+- Source-to-target data mapping onaylandı.
+- Poyraz UI v3 kararı ADR-0006 olarak güncellendi.
+- Local typecheck/lint/build/smoke baseline'ı kaydedildi.
+
+Açık dış veri:
+
+- Production Supabase gerçek satır sayıları
+- Production status dağılımları
+- Storage bucket dosya sayısı ve toplam boyut
+- Storage orphan path raporu
+
+Bu dış veri kalemleri için hazır audit sorguları vardır; read-only export veya erişim sağlandığında Faz 0'ın son açık checklist maddesi kapatılacaktır.
diff --git a/docs/self-hosted-redesign/phase-0-data-mapping.md b/docs/self-hosted-redesign/phase-0-data-mapping.md
index e2c6996..6cb96bf 100644
--- a/docs/self-hosted-redesign/phase-0-data-mapping.md
+++ b/docs/self-hosted-redesign/phase-0-data-mapping.md
@@ -1,13 +1,13 @@
 ---
 title: Phase 0 Data Mapping
-description: Supabase kaynak modelinden SQLite/Next.js hedef modeline ilk mapping ve production audit sorguları.
+description: Supabase kaynak modelinden SQLite/Next.js hedef modeline onaylı mapping ve production audit sorguları.
 status: active
-last_updated: 2026-07-10
+last_updated: 2026-07-16
 ---
 
 # Phase 0 Data Mapping
 
-Bu dosya Faz 0 için source-to-target veri mapping taslağıdır. Production verisine bağlanmadan status dağılımı ve gerçek satır sayısı tamamlanamaz; bu nedenle her production-only madde audit sorgularıyla birlikte bırakılmıştır.
+Bu dosya Faz 0 için onaylı source-to-target veri mapping'idir. Production verisine bağlanmadan status dağılımı ve gerçek satır sayısı tamamlanamaz; bu nedenle her production-only madde audit sorgularıyla birlikte bırakılmıştır. Alan düzeyi nihai Drizzle schema Faz 2'de üretilecek, ancak tablo kaderi ve normalization kuralları bu belgeyle kilitlenmiştir.
 
 ## Kanonik veri standartları
 
@@ -24,8 +24,8 @@ Bu dosya Faz 0 için source-to-target veri mapping taslağıdır. Production ver
 | Supabase kaynak | Mevcut amaç | Hedef model | Karar |
 | --- | --- | --- | --- |
 | `auth.users` | Supabase auth principal, freelancer/client user | Better Auth user/session/account tabloları | Password/session taşınmayacak; reset veya yeniden davet |
-| `profiles` | Ad, avatar, role | `profiles` veya Better Auth user extension | `role: freelancer|client` korunur |
-| `clients` | CRM client ve portal auth link | `clients` | `client_auth_id` nullable relation olarak korunur |
+| `profiles` | Ad, avatar, role | `app_profiles` | `role: freelancer|client` korunur; tek owner setup guard ile sağlanır |
+| `clients` | CRM client ve portal auth link | `clients` | `auth_user_id` nullable; invitation kabulünde transaction ile kurulur |
 | `client_activities` | Client timeline | `client_activities` | Sahiplik `owner_user_id` ile |
 | `projects` | Proje kayıtları, progress, quota, cover image | `projects` | `budget_amount` minor unit; cover image file metadata |
 | `project_planning_sections` | Project planning content | `project_planning_sections` | `category` ve `sort_order` kanonik |
@@ -33,20 +33,31 @@ Bu dosya Faz 0 için source-to-target veri mapping taslağıdır. Production ver
 | `tasks` | Task/kanban | `tasks` | Status kanoniği `todo|in_progress|done|cancelled`; legacy `completed` normalize edilir |
 | `calendar_events` | Takvim | `calendar_events` | Visible range indexleri |
 | `finance_transactions` | Gelir/gider | `finance_transactions` | Amount integer minor unit |
-| `proposals` | Teklifler | `proposals` | Faz 5'te gerçek mutation ihtiyacı doğrulanacak |
-| `contracts` | Sözleşmeler | `contracts` | Faz 5'te gerçek mutation ihtiyacı doğrulanacak |
-| `invoices` | Faturalar | `invoices` | Amount/tax minor unit |
-| `subscriptions` | Recurring expenses | `subscriptions` | Billing cycle enum korunur |
+| `proposals` | Teklifler | `proposals` veya açık archive eşleniği | Veri korunur; UI/CRUD release-blocker değildir |
+| `contracts` | Sözleşmeler | `contracts` veya açık archive eşleniği | Veri korunur; UI/CRUD release-blocker değildir |
+| `invoices` | Faturalar | `invoices` veya açık archive eşleniği | Amount/tax minor unit; UI/CRUD release-blocker değildir |
+| `subscriptions` | Recurring expenses | `subscriptions` veya açık archive eşleniği | Billing cycle enum korunur; UI/CRUD release-blocker değildir |
 | `daily_logs` | Aktif journal ekranı | `journal_entries` | `journals` ile birleştirilecek |
 | `journals` | Legacy AI journal | `journal_entries` archive/import source | Aynı güne denk gelen kayıtlar merge rule ile |
 | `chat_sessions` | AI chat session | `chat_sessions` | Browser DB erişimi kaldırılır |
 | `chat_messages` | AI chat messages | `chat_messages` | Message role enum validate edilir |
 | `document_embeddings` | pgvector RAG | Archive table veya import dışı | İlk release'te operational vector search yok |
-| `app_settings` | Timezone/currency/AI settings | `user_settings` | `api_key` taşınmaz veya sadece masked migration warning |
+| `app_settings` | Timezone/currency/AI settings | `user_preferences` + server-side AI secret config | `api_key` taşınmaz; yalnızca migration warning/count |
 | `storage.objects` bucket `avatars` | Avatar dosyaları | `files` + `/uploads/avatars` | Public read yerine authorized handler veya static controlled path |
 | `storage.objects` bucket `project-assets` | Project cover/assets | `files` + `/uploads/project-assets` | MIME/magic byte/size checks |
 | `neta_internal.internal_auth_creations` | Service-role guarded auth creation handshake | Kaldırılır | Better Auth invite/setup flow ile gerek kalmaz |
 
+Hedefte kaynaktan türemeyen yeni tablolar:
+
+| Hedef model | Amaç | Faz 0 kararı |
+| --- | --- | --- |
+| `instance_settings` | Instance adı, support ve genel davranış | Singleton instance config |
+| `instance_branding` | Logo, renk, mode ve radius ayarları | Poyraz UI semantic token girdisi |
+| `user_preferences` | Tema tercihi, timezone, currency ve UI tercihleri | Kullanıcı bazlı; secret içermez |
+| `files` | Yerel dosya metadata ve güvenli relative path | İçerik `/app/data/uploads` altında |
+| `portal_invitations` | Süreli ve hash'lenmiş client invite token | Better Auth client self-activation |
+| `auth_audit_events` | Setup/login/logout güvenlik olayları | Mevcut SQLite model korunur |
+
 ## Enum/status baseline
 
 Kaynak schema ve koddan görülen status/type değerleri:
@@ -96,6 +107,8 @@ Hedefte RLS yok; bu policy'ler service/repository authorization testlerine çevr
 
 Bu sorgular Supabase SQL Editor veya read-only connection ile çalıştırılmalı. Secret değerleri loglanmamalı.
 
+2026-07-16 durumu: workspace'te yalnızca `.env.example` bulunduğu için bu sorgular production üzerinde çalıştırılmamıştır. Kaynak schema envanteri 19 ürün/public tablo, 1 internal tablo ve 2 storage bucket olarak doğrulanmıştır; gerçek satır/dosya sayıları açık kalmıştır.
+
 ```sql
 select 'profiles' as table_name, count(*) from public.profiles
 union all select 'clients', count(*) from public.clients
@@ -190,4 +203,3 @@ Money:
 
 - `amount numeric(12,2)` ve `budget_amount numeric(12,2)` hedefte `amount_minor integer` veya `budget_amount_minor integer`.
 - Currency her row'da ISO-like text olarak korunur; kullanıcı default currency migration sırasında sadece fallback.
-
diff --git a/docs/self-hosted-redesign/phase-0-fixtures.md b/docs/self-hosted-redesign/phase-0-fixtures.md
index e60a6d2..0c306be 100644
--- a/docs/self-hosted-redesign/phase-0-fixtures.md
+++ b/docs/self-hosted-redesign/phase-0-fixtures.md
@@ -2,7 +2,7 @@
 title: Phase 0 Fixture Strategy
 description: Self-hosted redesign boyunca kullanılacak küçük ve stres veri setlerinin kapsamı.
 status: active
-last_updated: 2026-07-10
+last_updated: 2026-07-16
 ---
 
 # Phase 0 Fixture Strategy
@@ -24,9 +24,12 @@ Amaç: Core smoke ve regression testleri hızlı çalışsın.
 
 Önerilen içerik:
 
-- 1 freelancer user
+- 1 aktif freelancer/owner user
+- UI'da kullanılamayan 1 foreign-owner test principal ve yalnızca negatif authorization fixture'ları
 - 2 clients
 - 1 portal client user
+- 1 accepted ve 1 expired portal invitation
+- 1 instance settings ve 1 instance branding kaydı
 - 3 projects: `planning`, `active`, `completed`
 - 1 project `progress_type=auto`
 - 8 tasks: `todo`, `in_progress`, `done`, private/public portal task karışık
@@ -36,8 +39,10 @@ Amaç: Core smoke ve regression testleri hızlı çalışsın.
 - 2 planning sections: `overview`, `scope`, sıralı `sort_order`
 - 2 revision requests: `pending`, `completed`
 - 1 avatar metadata kaydı
+- 2 branding logo/icon metadata kaydı
 - 1 project cover file metadata kaydı
 - 1 chat session ve 2 message
+- Import koruma testi için 1 proposal, 1 contract, 1 invoice ve 1 subscription source fixture
 
 Bu fixture REG-001, REG-002, REG-003, REG-004, REG-005 ve cross-owner negatif testleri desteklemeli.
 
@@ -47,7 +52,7 @@ Amaç: Dashboard/list query performansını ve pagination zorunluluğunu test et
 
 Önerilen içerik:
 
-- 1 freelancer user
+- 1 freelancer/owner user
 - 100 clients
 - 250 projects
 - 2,500 tasks
@@ -82,4 +87,3 @@ Her rehearsal çıktısı:
 - File checksum manifest.
 - Restore command.
 - Smoke test sonucu.
-
diff --git a/docs/self-hosted-redesign/phase-0-regression-and-spike.md b/docs/self-hosted-redesign/phase-0-regression-and-spike.md
index dc41dd7..666c62a 100644
--- a/docs/self-hosted-redesign/phase-0-regression-and-spike.md
+++ b/docs/self-hosted-redesign/phase-0-regression-and-spike.md
@@ -2,7 +2,7 @@
 title: Phase 0 Regression and Phase 1 Spike Criteria
 description: Mevcut hatalardan türetilen regression testleri ve Faz 1 runtime spike kabul kriterleri.
 status: active
-last_updated: 2026-07-10
+last_updated: 2026-07-16
 ---
 
 # Phase 0 Regression and Phase 1 Spike Criteria
@@ -23,10 +23,14 @@ Bu maddeler davranış paritesi değildir; redesign içinde düzeltilmesi zorunl
 | REG-008 | Limitsiz listeler payload büyütüyor | Projects/tasks/clients/calendar list query contract incelenir | Pagination veya visible date range zorunlu |
 | REG-009 | Auto progress transaction dışı kalabilir | Task status değişimi auto progress project'te yapılır | Task update ve project progress aynı transaction sonucu |
 | REG-010 | Cross-owner UUID erişimi | Başka owner'a ait project/task/client UUID ile query/mutation yapılır | 404 veya authorization error; veri dönmez |
+| REG-011 | Production build `/app/data` oluşturmaya çalışıyor | Env verilmeden ve kontrollü build env ile standalone build alınır | Build host root'una yazmaz; runtime data dir yalnızca runtime'da hazırlanır |
+| REG-012 | Pnpm native build scriptleri ignore ediliyor | Fresh `pnpm install` sonrası SQLite smoke çalıştırılır | `better-sqlite3` native binding mevcut; smoke yükleme hatası vermez |
+| REG-013 | Better Auth layout + Supabase feature session ayrışması | Better Auth ile login sonrası core feature read/mutation çalıştırılır | Tek session principal kullanılır; Supabase session gerekmiyor |
+| REG-014 | Eksik link hedefleri | Login forgot-password ve portal settings linkleri izlenir | Her görünür link gerçek route veya bilinçli disabled state'e gider |
 
-## Behavior smoke matrix
+## Kritik davranış baseline matrisi
 
-Faz 0 sırasında ekran kaydı alınması gereken kritik akışlar:
+Faz 0'da mevcut kod davranışı `phase-0-baseline.md` içinde kaydedilmiştir. Hibrit auth nedeniyle eski ekranın canlı çalışması yeni sistem için güvenilir parity kanıtı değildir. Aşağıdaki akışların yeni vertical slice kabulünde ekran kaydı veya tekrarlanabilir browser smoke çıktısı alınacaktır:
 
 | Akış | Kayıt adı önerisi | Kapsam |
 | --- | --- | --- |
@@ -78,4 +82,3 @@ Rollback:
 - Faz 1 spike production'a deploy edilmez.
 - Eski Supabase app untouched kalır.
 - Spike branch silinebilir veya ADR yeniden açılır.
-
diff --git a/docs/self-hosted-redesign/phase-3-ui.md b/docs/self-hosted-redesign/phase-3-ui.md
index cf4af47..54d43c7 100644
--- a/docs/self-hosted-redesign/phase-3-ui.md
+++ b/docs/self-hosted-redesign/phase-3-ui.md
@@ -1,5 +1,7 @@
 # Phase 3 UI Implementation Notes
 
+> Tarihsel not: Bu belgede uygulanan internal UI yönü 2026-07-16 tarihli ADR-0006 ile supersede edilmiştir. İleriye dönük hedef Poyraz UI v3'ü tek genel UI sistemi olarak kullanmaktır. Buradaki internal primitive ve shell'ler geçiş/baseline kodu olarak değerlendirilmelidir.
+
 ## Kapsam
 
 Bu fazda Poyraz UI tamamen package seviyesinde kaldırılmadı. Mevcut feature sayfaları hâlâ Poyraz component import ediyor ve Faz 4-6 sırasında veri/UI birlikte taşınacak. Faz 3 uygulaması yeni internal primitive setini, auth shell'i ve dashboard/portal shell'i Poyraz import sınırından ayırır.