diff --git a/CHANGELOG.md b/CHANGELOG.md
index 69c090a..ebdc4f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on Keep a Changelog:
 https://keepachangelog.com/en/1.1.0/
 
+## [Unreleased]
+
+### Docs
+
+- Strengthened the bilingual documentation system with direct links, release guidance, governance guidance, and clearer usage flows.
+- Clarified that npm publication and the first GitHub release have not happened yet.
+
 ## [0.1.0] - 2026-03-09
 
 ### Added
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 362409f..067bb21 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -26,7 +26,11 @@ Project maintainers are responsible for clarifying and enforcing this Code of Co
 
 ## Reporting
 
-If you experience or witness unacceptable behavior, report it to the maintainers through GitHub using a private channel whenever possible. Public issue threads should not be used for sensitive reports.
+If you experience or witness unacceptable behavior:
+
+1. do not use public issue threads for sensitive reports
+2. contact the maintainer privately through GitHub
+3. if the report overlaps with a security issue, follow `SECURITY.md` instead
 
 ## Scope
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6ea2680..e945352 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,6 +2,12 @@
 
 Thanks for contributing.
 
+## Repository Reality
+
+- CI and protected-branch automation are active.
+- npm release automation is configured but the first public release has not happened yet.
+- Documentation is maintained in both English and Turkish for user-facing topics.
+
 ## Local Setup
 
 1. Install Bun.
@@ -54,6 +60,7 @@ The repository includes a GitHub release workflow for npm publishing.
 
 ## Further Reading
 
-- `docs/README.md`
-- `docs/en/usage-guide.md`
-- `docs/en/model-recommendations.md`
+- [Documentation Hub](./docs/README.md)
+- [Usage Guide](./docs/en/usage-guide.md)
+- [Pull Request Guide](./docs/en/pull-request-guide.md)
+- [Release Guide](./docs/en/release-guide.md)
diff --git a/README.md b/README.md
index 5db8680..3b2d385 100644
--- a/README.md
+++ b/README.md
@@ -4,43 +4,86 @@
 [![Release](https://github.com/vaur94/opencode-ceo/actions/workflows/release.yml/badge.svg)](https://github.com/vaur94/opencode-ceo/actions/workflows/release.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-Transform OpenCode into a deterministic software company OS.
+Build a disciplined, delivery-aware OpenCode workflow with a CEO agent, specialist delegation, persistent state, and GitHub handoff.
 
-`opencode-ceo` is an OpenCode plugin that runs software work through a controlled delivery pipeline. The CEO agent decomposes work, delegates to specialists, enforces gates, persists artifacts/state, and can deliver changes into GitHub with branch and pull request automation.
+## 🚀 What This Project Does
 
-## Language
+`opencode-ceo` is an OpenCode plugin that turns software work into a controlled delivery pipeline. Instead of letting one agent improvise the whole task, it moves work through defined stages, persists decisions and artifacts, and can prepare Git branches and pull requests when the repository is ready.
 
-- English: `README.md`
-- Turkish: `README.tr.md`
+## 🌍 Language Options
 
-## Why opencode-ceo?
+- [English README](./README.md)
+- [Turkce README](./README.tr.md)
 
-- Deterministic pipeline ownership instead of ad-hoc agent output.
-- SQLite-backed state and artifact persistence for long-running work.
-- Delivery-aware GitHub tooling for branches, PRs, and repository fingerprinting.
-- Gated autonomy levels for teams that want review points before delivery.
+## ⚡ Status At A Glance
 
-## Documentation Map
+- CI on `main`: enabled and protected
+- Release workflow: configured in `.github/workflows/release.yml`
+- Dependabot: configured in `.github/dependabot.yml`
+- npm package publication: not published yet
+- GitHub release: not created yet
 
-| Topic | English | Turkish |
-|------|---------|---------|
-| Documentation hub | `docs/README.md` | `docs/README.md` |
-| Usage guide | `docs/en/usage-guide.md` | `docs/tr/kullanim-kilavuzu.md` |
-| PR guide | `docs/en/pull-request-guide.md` | `docs/tr/pr-kilavuzu.md` |
-| Model recommendations | `docs/en/model-recommendations.md` | `docs/tr/model-onerileri.md` |
-| Architecture | `docs/ARCHITECTURE.md` | `docs/ARCHITECTURE.md` |
-| Contributing | `CONTRIBUTING.md` | `CONTRIBUTING.md` |
-| Security | `SECURITY.md` | `SECURITY.md` |
-| Support | `SUPPORT.md` | `SUPPORT.md` |
-| Changelog | `CHANGELOG.md` | `CHANGELOG.md` |
+If you are evaluating release readiness, start with the [Release Guide](./docs/en/release-guide.md).
 
-## Installation
+## ✨ Why opencode-ceo?
+
+- Deterministic pipeline ownership instead of one-shot agent output
+- SQLite-backed artifacts, gates, and state for long-running sessions
+- GitHub-aware delivery helpers for branch and PR preparation
+- Configurable autonomy for teams that want review gates before delivery
+
+## 🧭 Documentation Hub
+
+Start here if you want the full docs map:
+
+- [Documentation Hub](./docs/README.md)
+
+### Table of Contents
+
+- [What This Project Does](#-what-this-project-does)
+- [Status At A Glance](#-status-at-a-glance)
+- [Documentation Hub](#-documentation-hub)
+- [Installation Status](#-installation-status)
+- [Configuration Example](#️-configuration-example)
+- [Pipeline Overview](#️-pipeline-overview)
+- [GitHub Delivery](#-github-delivery)
+- [Local Verification](#-local-verification)
+- [Repository Controls](#️-repository-controls)
+
+Core guides:
+
+- [Usage Guide](./docs/en/usage-guide.md)
+- [Pull Request Guide](./docs/en/pull-request-guide.md)
+- [Model Recommendations](./docs/en/model-recommendations.md)
+- [Release Guide](./docs/en/release-guide.md)
+- [Governance and Branch Policy](./docs/en/governance-guide.md)
+- [Architecture](./docs/ARCHITECTURE.md)
+
+Repository policies:
+
+- [Contributing](./CONTRIBUTING.md)
+- [Security](./SECURITY.md)
+- [Support](./SUPPORT.md)
+- [Code of Conduct](./CODE_OF_CONDUCT.md)
+- [Changelog](./CHANGELOG.md)
+- [License](./LICENSE)
+
+## 📦 Installation Status
+
+The package name is `opencode-ceo`, but the first public npm release has not been published yet.
+
+Current options:
+
+- local development from this repository
+- future npm install after the first release
+
+Planned install command after publication:
 
 ```bash
 npm install opencode-ceo
 ```
 
-Add the plugin to your `opencode.json` configuration:
+## ⚙️ Configuration Example
 
 ```json
 {
@@ -60,9 +103,7 @@ Add the plugin to your `opencode.json` configuration:
 }
 ```
 
-## Quick Start
-
-The smallest setup uses full autonomy:
+Minimal full-autonomy setup:
 
 ```json
 {
@@ -77,84 +118,45 @@ The smallest setup uses full autonomy:
 }
 ```
 
-Once configured, the `ceo` agent owns the task, delegates to hidden specialists, and advances the pipeline until work is blocked, failed, or completed.
+## 🏗️ Pipeline Overview
 
-## GitHub Delivery
+```text
+[intake] -> [decompose] -> [implement] -> [review] -> [test] -> [deliver] -> [completed]
+                 \-> [blocked]                                 \-> [failed]
+```
 
-`opencode-ceo` includes a GitHub-aware delivery path:
+Stage summary:
 
-- `ceo_branch_prepare` creates `ceo/<pipeline-id>/<slug>` branches.
-- `ceo_pr_prepare` pushes the active branch to `origin` and opens a PR with `gh pr create`.
-- `ceo_repo_fingerprint` reports git state, remote information, and repository readiness.
+- `intake`: capture the task and detect the project stack
+- `decompose`: build an implementation plan
+- `implement`: produce the change set
+- `review`: inspect correctness and risk
+- `test`: validate behavior and regression safety
+- `deliver`: prepare branch and PR output
 
-Authenticate GitHub CLI before using the PR automation path:
+For deeper detail, see [Architecture](./docs/ARCHITECTURE.md).
 
-```bash
-gh auth login
-```
+## 🧠 Model Preferences
 
-## Configuration
+You can tune `modelPreferences` by stage. Suggested defaults and trade-offs live here:
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `autonomyLevel` | `full` \| `gated` \| `manual` | `full` | Controls how much human intervention is required for pipeline transitions. |
-| `gates` | `Record<string, "auto" \| "manual">` | `{}` | Configures specific approval gates such as `approve-plan` or `approve-delivery`. |
-| `disabledAgents` | `string[]` | `[]` | Disables selected specialist agents. |
-| `modelPreferences` | `Object` | `{}` | Overrides preferred models for stages such as implement, review, and test. |
+- [Model Recommendations](./docs/en/model-recommendations.md)
 
-For practical model suggestions, see `docs/en/model-recommendations.md`.
+## 🔀 GitHub Delivery
 
-## Agents
+`opencode-ceo` includes GitHub-aware delivery tools:
 
-The plugin provides one primary CEO agent and seven hidden specialists.
+- `ceo_branch_prepare` creates `ceo/<pipeline-id>/<slug>` branches
+- `ceo_pr_prepare` pushes the active branch to `origin` and opens a PR with `gh pr create`
+- `ceo_repo_fingerprint` reports remote, git status, and general repo readiness
 
-| Agent ID | Purpose | Hidden |
-|----------|---------|--------|
-| `ceo` | Owns the delivery pipeline and delegates work. | No |
-| `ceo-architect` | Breaks complex work into implementation-ready plans. | Yes |
-| `ceo-implementer` | Implements scoped code changes and validates them locally. | Yes |
-| `ceo-reviewer` | Reviews code changes for correctness and risk. | Yes |
-| `ceo-tester` | Runs focused validation and safety checks. | Yes |
-| `ceo-ts-specialist` | Handles TypeScript-heavy implementation and type issues. | Yes |
-| `ceo-python-specialist` | Handles Python-specific implementation and runtime issues. | Yes |
-| `ceo-go-specialist` | Handles Go-specific implementation and tooling issues. | Yes |
+Before using PR automation locally:
 
-## Pipeline Stages
-
-```text
-[intake] -> [decompose] -> [implement] -> [review] -> [test] -> [deliver] -> [completed]
-                 \-> [blocked]                                 \-> [failed]
+```bash
+gh auth login
 ```
 
-| Stage | Description | Primary Agent |
-|-------|-------------|---------------|
-| **Intake** | Initial task analysis and feasibility check. | `ceo` |
-| **Decompose** | Breaking the task into a concrete implementation plan. | `ceo-architect` |
-| **Implement** | Writing code and performing local verification. | `ceo-implementer` |
-| **Review** | Peer review of changes for quality and standards. | `ceo-reviewer` |
-| **Test** | Rigorous verification using test suites and CI-like checks. | `ceo-tester` |
-| **Deliver** | Final packaging and submission. | `ceo` |
-
-## Tool List
-
-| Tool | Purpose |
-|------|---------|
-| `ceo_delegate` | Delegate work to a hidden subagent with explicit tool restrictions. |
-| `ceo_stage_transition` | Move the pipeline through valid FSM states. |
-| `ceo_gate_run` | Run an approval gate and optionally request manual approval. |
-| `ceo_gate_status` | Inspect gate state for a pipeline. |
-| `ceo_artifact_write` | Persist stage artifacts in SQLite-backed storage. |
-| `ceo_artifact_read` | Read persisted artifacts. |
-| `ceo_decision_log` | Record decisions in the audit trail. |
-| `ceo_branch_prepare` | Create a delivery branch. |
-| `ceo_pr_prepare` | Create a PR and persist its URL artifact. |
-| `ceo_repo_fingerprint` | Return repository metadata, remote info, and git status. |
-| `ceo_stack_detect` | Detect the active project stack. |
-| `ceo_delivery_format` | Produce a markdown delivery summary. |
-| `ceo_context_pack` | Pack SQLite-backed state for compaction. |
-| `ceo_context_restore` | Restore packed state after compaction or resume. |
-
-## Development
+## 🧪 Local Verification
 
 ```bash
 bun install
@@ -168,20 +170,25 @@ Useful individual commands:
 - `bun test`
 - `bun run pack:check`
 
-## Repository Standards
+## 🛡️ Repository Controls
+
+- protected `main` branch
+- required `quality`, `tests`, and `package` checks
+- linear history enforced
+- force-push disabled on `main`
+- conversations must be resolved before merge
+- Dependabot active for npm and GitHub Actions
+- CI currently listens to both `main` and `master` for compatibility, while `main` is the active branch policy target
 
-- CI is enforced on `main` with separate quality, test, and package checks.
-- Release publishing runs from tags through `.github/workflows/release.yml`.
-- Dependabot is configured for npm and GitHub Actions updates.
-- Branch protection requires reviews and passing checks before merge.
+Details: [Governance and Branch Policy](./docs/en/governance-guide.md)
 
-## Next Docs
+## 📚 Next Steps
 
-- Getting started and operations: `docs/en/usage-guide.md`
-- Pull request process: `docs/en/pull-request-guide.md`
-- Model tuning by stage: `docs/en/model-recommendations.md`
-- Architecture details: `docs/ARCHITECTURE.md`
+- operational setup: [Usage Guide](./docs/en/usage-guide.md)
+- contribution flow: [Pull Request Guide](./docs/en/pull-request-guide.md)
+- release flow: [Release Guide](./docs/en/release-guide.md)
+- repo policy: [Governance and Branch Policy](./docs/en/governance-guide.md)
 
-## License
+## 📄 License
 
 MIT
diff --git a/README.tr.md b/README.tr.md
index b2206b6..165f800 100644
--- a/README.tr.md
+++ b/README.tr.md
@@ -4,43 +4,86 @@
 [![Release](https://github.com/vaur94/opencode-ceo/actions/workflows/release.yml/badge.svg)](https://github.com/vaur94/opencode-ceo/actions/workflows/release.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-OpenCode'u daha kontrollu, izlenebilir ve teslimat odakli bir yazi lim sirketi isletim sistemine donusturur.
+OpenCode icin daha kontrollu, izlenebilir ve teslimat odakli bir yazilim operasyon sistemi kurar.
 
-`opencode-ceo`, isleri asamali bir teslimat hattindan geciren bir OpenCode eklentisidir. CEO ajanı isi parcala, uzman ajanlara delege eder, kapilari uygular, artifact ve state bilgisini saklar, gerekirse GitHub branch ve PR akisina kadar teslimati yonetir.
+## 🚀 Bu Proje Ne Yapiyor?
 
-## Dil
+`opencode-ceo`, yazilim gorevlerini belirli asamalardan geciren bir OpenCode eklentisidir. CEO ajanı isi sahiplenir, uzman ajanlara delege eder, kapilari uygular, artifact ve state bilgisini saklar, uygun oldugunda GitHub branch ve PR teslimatini da hazirlar.
 
-- English: `README.md`
-- Turkce: `README.tr.md`
+## 🌍 Dil Secenekleri
 
-## Neden opencode-ceo?
+- [English README](./README.md)
+- [Turkce README](./README.tr.md)
 
-- Duzensiz agent ciktilari yerine belirli bir pipeline kullanir.
-- SQLite tabanli state ve artifact saklama ile uzun suren oturumlari destekler.
-- GitHub branch ve PR akisi icin hazir araclar sunar.
-- Tam otomasyon ile kontrollu onay noktalarini ayni sistemde toplar.
+## ⚡ Guncel Durum
 
-## Dokuman Haritasi
+- `main` branch CI korumasi aktif
+- release workflow hazir: `.github/workflows/release.yml`
+- Dependabot aktif: `.github/dependabot.yml`
+- npm paketi henuz yayinlanmadi
+- GitHub release henuz olusturulmadi
 
-| Konu | English | Turkce |
-|------|---------|--------|
-| Dokuman merkezi | `docs/README.md` | `docs/README.md` |
-| Kullanim kilavuzu | `docs/en/usage-guide.md` | `docs/tr/kullanim-kilavuzu.md` |
-| PR rehberi | `docs/en/pull-request-guide.md` | `docs/tr/pr-kilavuzu.md` |
-| Model onerileri | `docs/en/model-recommendations.md` | `docs/tr/model-onerileri.md` |
-| Mimari | `docs/ARCHITECTURE.md` | `docs/ARCHITECTURE.md` |
-| Katki rehberi | `CONTRIBUTING.md` | `CONTRIBUTING.md` |
-| Guvenlik | `SECURITY.md` | `SECURITY.md` |
-| Destek | `SUPPORT.md` | `SUPPORT.md` |
-| Degisiklik gunlugu | `CHANGELOG.md` | `CHANGELOG.md` |
+Release durumunu ve yayin adimlarini gormek icin [Surum ve Yayin Rehberi](./docs/tr/surum-yayin-rehberi.md) ile baslayin.
 
-## Kurulum
+## ✨ Neden opencode-ceo?
+
+- tek seferlik agent cevabi yerine kontrollu bir pipeline kullanir
+- uzun sureli islerde SQLite tabanli state ve artifact takibi saglar
+- GitHub branch ve PR teslimati icin hazir araclar sunar
+- tam otomasyon ile manuel onay noktalarini ayni sistemde toplar
+
+## 🧭 Dokuman Merkezi
+
+Tum dokuman yapisi icin:
+
+- [Dokuman Merkezi](./docs/README.md)
+
+### Icindekiler
+
+- [Bu Proje Ne Yapiyor?](#-bu-proje-ne-yapiyor)
+- [Guncel Durum](#-guncel-durum)
+- [Dokuman Merkezi](#-dokuman-merkezi)
+- [Kurulum Durumu](#-kurulum-durumu)
+- [Konfigurasyon Ornegi](#️-konfigurasyon-ornegi)
+- [Pipeline Ozeti](#️-pipeline-ozeti)
+- [GitHub Teslimat Akisi](#-github-teslimat-akisi)
+- [Yerel Dogrulama](#-yerel-dogrulama)
+- [Repo Kontrolleri](#️-repo-kontrolleri)
+
+Temel rehberler:
+
+- [Kullanim Kilavuzu](./docs/tr/kullanim-kilavuzu.md)
+- [PR Kilavuzu](./docs/tr/pr-kilavuzu.md)
+- [Model Onerileri](./docs/tr/model-onerileri.md)
+- [Surum ve Yayin Rehberi](./docs/tr/surum-yayin-rehberi.md)
+- [Yonetsim ve Branch Politikasi](./docs/tr/yonetisim-rehberi.md)
+- [Mimari](./docs/ARCHITECTURE.md)
+
+Repo politikalari:
+
+- [Katki Rehberi](./CONTRIBUTING.md)
+- [Guvenlik](./SECURITY.md)
+- [Destek](./SUPPORT.md)
+- [Davranis Kurallari](./CODE_OF_CONDUCT.md)
+- [Degisiklik Gunlugu](./CHANGELOG.md)
+- [Lisans](./LICENSE)
+
+## 📦 Kurulum Durumu
+
+Paket adi `opencode-ceo`, ancak ilk genel npm yayini henuz yapilmadi.
+
+Bugun icin gercek kullanim secenekleri:
+
+- bu repo uzerinden yerel gelistirme
+- ilk yayin sonrasi `npm install`
+
+Ilk yayin sonrasi planlanan komut:
 
 ```bash
 npm install opencode-ceo
 ```
 
-`opencode.json` icine eklenti ayarini ekleyin:
+## ⚙️ Konfigurasyon Ornegi
 
 ```json
 {
@@ -60,9 +103,7 @@ npm install opencode-ceo
 }
 ```
 
-## Hizli Baslangic
-
-En kucuk kurulum icin tam otonomi kullanabilirsiniz:
+En kucuk tam otonomi kurulumu:
 
 ```json
 {
@@ -77,45 +118,75 @@ En kucuk kurulum icin tam otonomi kullanabilirsiniz:
 }
 ```
 
-Bu kurulumdan sonra `ceo` ajanı isi sahiplenir, gizli uzman ajanlara delege eder ve pipeline son durumuna kadar ilerler.
+## 🏗️ Pipeline Ozeti
 
-## GitHub Teslimat Akisi
+```text
+[intake] -> [decompose] -> [implement] -> [review] -> [test] -> [deliver] -> [completed]
+                 \-> [blocked]                                 \-> [failed]
+```
 
-- `ceo_branch_prepare`, `ceo/<pipeline-id>/<slug>` adlandirmasi ile branch olusturur.
-- `ceo_pr_prepare`, aktif branch'i `origin`e push eder ve `gh pr create` ile PR acar.
-- `ceo_repo_fingerprint`, repo durumu, remote bilgisi ve git durumunu raporlar.
+Asama ozeti:
 
-Yerel PR otomasyonu icin once GitHub CLI girisi yapin:
+- `intake`: gorev alinır ve proje stack'i tespit edilir
+- `decompose`: uygulanabilir plan olusturulur
+- `implement`: degisiklik uretimi yapilir
+- `review`: kalite ve risk kontrolu yapilir
+- `test`: davranis ve regresyon kontrolleri calistirilir
+- `deliver`: branch ve PR ciktilari hazirlanir
 
-```bash
-gh auth login
-```
+Daha fazla ayrinti icin [Mimari](./docs/ARCHITECTURE.md) dosyasina bakin.
+
+## 🧠 Model Tercihleri
+
+`modelPreferences` ayarlarini asama bazinda optimize edebilirsiniz:
+
+- [Model Onerileri](./docs/tr/model-onerileri.md)
+
+## 🔀 GitHub Teslimat Akisi
 
-## Konfigurasyon
+- `ceo_branch_prepare`, `ceo/<pipeline-id>/<slug>` branch'i olusturur
+- `ceo_pr_prepare`, aktif branch'i `origin`e push eder ve `gh pr create` ile PR acar
+- `ceo_repo_fingerprint`, remote, git durumu ve repo hazirlik bilgisini raporlar
 
-| Secenek | Tip | Varsayilan | Aciklama |
-|---------|-----|------------|----------|
-| `autonomyLevel` | `full` \| `gated` \| `manual` | `full` | Pipeline gecislerinde insan mudahalesi seviyesini belirler. |
-| `gates` | `Record<string, "auto" \| "manual">` | `{}` | `approve-plan` ve `approve-delivery` gibi kapilari tanimlar. |
-| `disabledAgents` | `string[]` | `[]` | Belirli uzman ajanlari devre disi birakir. |
-| `modelPreferences` | `Object` | `{}` | Implement, review ve test gibi asamalarda tercih edilen modelleri belirler. |
+Yerel PR otomasyonu icin once:
 
-Pratik model tavsiyeleri icin `docs/tr/model-onerileri.md` dosyasina bakin.
+```bash
+gh auth login
+```
 
-## Gelistirme
+## 🧪 Yerel Dogrulama
 
 ```bash
 bun install
 bun run ci:verify
 ```
 
-## Sonraki Dokumanlar
+Tekil komutlar:
+
+- `bun run build`
+- `bun run typecheck`
+- `bun test`
+- `bun run pack:check`
+
+## 🛡️ Repo Kontrolleri
+
+- korumali `main` branch
+- zorunlu `quality`, `tests`, `package` kontrolleri
+- lineer history zorunlulugu
+- `main` icin force-push kapali
+- merge oncesi konusma cozum zorunlulugu
+- npm ve GitHub Actions icin Dependabot aktif
+- CI, geriye donuk uyumluluk icin hem `main` hem `master` olaylarini dinler; aktif politika hedefi `main` branch'idir
+
+Ayrintilar: [Yonetsim ve Branch Politikasi](./docs/tr/yonetisim-rehberi.md)
+
+## 📚 Sonraki Adimlar
 
-- Kullanim detaylari: `docs/tr/kullanim-kilavuzu.md`
-- PR akisi: `docs/tr/pr-kilavuzu.md`
-- Model tavsiyeleri: `docs/tr/model-onerileri.md`
-- Mimari detaylar: `docs/ARCHITECTURE.md`
+- kullanim: [Kullanim Kilavuzu](./docs/tr/kullanim-kilavuzu.md)
+- katkı ve PR akisi: [PR Kilavuzu](./docs/tr/pr-kilavuzu.md)
+- yayin akisi: [Surum ve Yayin Rehberi](./docs/tr/surum-yayin-rehberi.md)
+- repo kurallari: [Yonetsim ve Branch Politikasi](./docs/tr/yonetisim-rehberi.md)
 
-## Lisans
+## 📄 Lisans
 
 MIT
diff --git a/SECURITY.md b/SECURITY.md
index ab8a1ba..791a2c9 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -10,8 +10,8 @@ Please do not open public GitHub issues for security reports.
 
 Instead:
 
-1. use GitHub's private vulnerability reporting flow if it is enabled for the repository
-2. otherwise contact the maintainers through a private GitHub channel before public disclosure
+1. use the repository's GitHub Security reporting flow if the Security tab exposes "Report a vulnerability"
+2. if that flow is unavailable, contact the maintainer privately through GitHub before public disclosure
 
 When reporting a vulnerability, include:
 
@@ -24,5 +24,6 @@ We will acknowledge valid reports as quickly as possible and coordinate disclosu
 
 ## Related Documents
 
-- `SUPPORT.md`
-- `CONTRIBUTING.md`
+- [Support](./SUPPORT.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Governance and Branch Policy](./docs/en/governance-guide.md)
diff --git a/SUPPORT.md b/SUPPORT.md
index c2eae3e..90e9cb5 100644
--- a/SUPPORT.md
+++ b/SUPPORT.md
@@ -9,9 +9,17 @@ Use the following paths so requests land in the right place:
 
 When asking for help, include the commands you ran, the environment, and any relevant logs.
 
+For good bug reports, include:
+
+- exact reproduction steps
+- expected versus actual behavior
+- Bun version and operating system
+- relevant logs or screenshots
+
 ## Useful References
 
-- `README.md`
-- `README.tr.md`
-- `docs/README.md`
-- `SECURITY.md`
+- [English README](./README.md)
+- [Turkce README](./README.tr.md)
+- [Documentation Hub](./docs/README.md)
+- [Security](./SECURITY.md)
+- [Usage Guide](./docs/en/usage-guide.md)
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index db1071b..75b9b9a 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -2,6 +2,15 @@
 
 This document describes the internal design and operational mechanics of the `opencode-ceo` plugin.
 
+## Table of Contents
+
+- [System Overview](#system-overview)
+- [FSM States](#fsm-states)
+- [Agent Contracts](#agent-contracts)
+- [Tool Catalog](#tool-catalog)
+- [State Schema](#state-schema)
+- [Compaction Survival](#compaction-survival)
+
 ## System Overview
 
 The `opencode-ceo` plugin implements a hierarchical agent model where a primary "CEO" agent manages the entire software delivery lifecycle by delegating specialized tasks to a fleet of subagents.
diff --git a/docs/README.md b/docs/README.md
index c6281a9..ce3dcba 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,27 +1,71 @@
 # Documentation Hub
 
-Use this page as the entry point for the repository documentation set.
+Use this page as the central entry point for the repository documentation set.
 
-## English
+## Start Here By Goal
 
-- `../README.md` - project overview
-- `en/usage-guide.md` - installation, configuration, operation, and troubleshooting
-- `en/pull-request-guide.md` - contribution and PR expectations
-- `en/model-recommendations.md` - suggested model profiles by pipeline stage
-- `ARCHITECTURE.md` - internal system design
+### I am evaluating the project
 
-## Turkce
+- [English README](../README.md)
+- [Turkce README](../README.tr.md)
+- [Architecture](./ARCHITECTURE.md)
 
-- `../README.tr.md` - proje genel bakis
-- `tr/kullanim-kilavuzu.md` - kurulum, konfigurasyon, kullanim ve sorun giderme
-- `tr/pr-kilavuzu.md` - PR ve katkı sureci
-- `tr/model-onerileri.md` - pipeline asamalarina gore model tavsiyeleri
-- `ARCHITECTURE.md` - sistem mimarisi
+### I want to use or test it locally
 
-## Repository Policies
+- [Usage Guide](./en/usage-guide.md)
+- [Kullanim Kilavuzu](./tr/kullanim-kilavuzu.md)
+- [Model Recommendations](./en/model-recommendations.md)
 
-- `../CONTRIBUTING.md`
-- `../SECURITY.md`
-- `../SUPPORT.md`
-- `../CODE_OF_CONDUCT.md`
-- `../CHANGELOG.md`
+### I want to contribute
+
+- [Contributing](../CONTRIBUTING.md)
+- [Pull Request Guide](./en/pull-request-guide.md)
+- [PR Kilavuzu](./tr/pr-kilavuzu.md)
+
+### I want to prepare a release
+
+- [Release Guide](./en/release-guide.md)
+- [Surum ve Yayin Rehberi](./tr/surum-yayin-rehberi.md)
+- [Changelog](../CHANGELOG.md)
+
+### I want governance or policy details
+
+- [Governance and Branch Policy](./en/governance-guide.md)
+- [Yonetsim ve Branch Politikasi](./tr/yonetisim-rehberi.md)
+- [Security](../SECURITY.md)
+- [Support](../SUPPORT.md)
+- [Code of Conduct](../CODE_OF_CONDUCT.md)
+
+## Quick Navigation
+
+- [English README](../README.md)
+- [Turkce README](../README.tr.md)
+- [Architecture](./ARCHITECTURE.md)
+- [Contributing](../CONTRIBUTING.md)
+- [Security](../SECURITY.md)
+- [Support](../SUPPORT.md)
+- [Changelog](../CHANGELOG.md)
+
+## English Guides
+
+- [Usage Guide](./en/usage-guide.md)
+- [Pull Request Guide](./en/pull-request-guide.md)
+- [Model Recommendations](./en/model-recommendations.md)
+- [Release Guide](./en/release-guide.md)
+- [Governance and Branch Policy](./en/governance-guide.md)
+
+## Turkce Rehberler
+
+- [Kullanim Kilavuzu](./tr/kullanim-kilavuzu.md)
+- [PR Kilavuzu](./tr/pr-kilavuzu.md)
+- [Model Onerileri](./tr/model-onerileri.md)
+- [Surum ve Yayin Rehberi](./tr/surum-yayin-rehberi.md)
+- [Yonetsim ve Branch Politikasi](./tr/yonetisim-rehberi.md)
+
+## Current Reality Check
+
+- npm publication has not happened yet
+- GitHub releases have not been created yet
+- CI, protected branch rules, and Dependabot are already active
+
+If you need release readiness details, go to the release guide first.
diff --git a/docs/en/governance-guide.md b/docs/en/governance-guide.md
new file mode 100644
index 0000000..4fdc1c3
--- /dev/null
+++ b/docs/en/governance-guide.md
@@ -0,0 +1,36 @@
+# Governance and Branch Policy
+
+## Branch Protection On `main`
+
+The repository is configured to keep `main` controlled:
+
+- required checks: `quality`, `tests`, `package`
+- linear history enabled
+- force-push disabled
+- conversation resolution required
+- admin enforcement enabled
+
+## Practical Merge Policy
+
+- open a PR for changes targeting `main`
+- keep PRs focused and reviewable
+- do not merge while required checks are red
+- resolve open review conversations before merge
+
+## Automation That Supports Governance
+
+- CI workflow in `.github/workflows/ci.yml`
+- release workflow in `.github/workflows/release.yml`
+- Dependabot in `.github/dependabot.yml`
+- PR template in `.github/PULL_REQUEST_TEMPLATE.md`
+
+## Current Limits
+
+- the first public release has not been created yet
+- npm publication has not happened yet
+
+## Related Docs
+
+- [Pull Request Guide](./pull-request-guide.md)
+- [Release Guide](./release-guide.md)
+- [Security](../../SECURITY.md)
diff --git a/docs/en/model-recommendations.md b/docs/en/model-recommendations.md
index 1826a2c..f638a1d 100644
--- a/docs/en/model-recommendations.md
+++ b/docs/en/model-recommendations.md
@@ -2,6 +2,15 @@
 
 This guide helps tune `modelPreferences` for the delivery stages.
 
+## Recommended Starting Point
+
+If you want a simple default setup:
+
+- use the strongest reasoning model you can afford for `decompose`
+- use a coding-oriented model for `implement`
+- keep `review` at least as strong as `implement`
+- use a cheaper, fast model for repetitive `test` loops
+
 ## General Rule
 
 - use high-reasoning models for planning and review
@@ -37,3 +46,8 @@ Replace those identifiers with the model IDs available in your OpenCode environm
 - optimize for consistency before cost-cutting
 - keep review stronger than test when budgets are tight
 - avoid mixing weak planning with strong implementation
+
+## Related Docs
+
+- [Usage Guide](./usage-guide.md)
+- [Release Guide](./release-guide.md)
diff --git a/docs/en/pull-request-guide.md b/docs/en/pull-request-guide.md
index a503bb7..ec87cb4 100644
--- a/docs/en/pull-request-guide.md
+++ b/docs/en/pull-request-guide.md
@@ -36,3 +36,9 @@ Use `.github/PULL_REQUEST_TEMPLATE.md` and include:
 - keep history readable and scoped
 - prefer small PRs over multi-topic batches
 - do not bypass branch protection except for emergencies
+
+## Related Docs
+
+- [Governance and Branch Policy](./governance-guide.md)
+- [Usage Guide](./usage-guide.md)
+- [Contributing](../../CONTRIBUTING.md)
diff --git a/docs/en/release-guide.md b/docs/en/release-guide.md
new file mode 100644
index 0000000..3243bb0
--- /dev/null
+++ b/docs/en/release-guide.md
@@ -0,0 +1,44 @@
+# Release Guide
+
+## Current Release Status
+
+- npm package: not published yet
+- GitHub release: not created yet
+- release workflow: configured in `.github/workflows/release.yml`
+
+## Before The First Release
+
+Make sure all of the following are true:
+
+- `bun run ci:verify` passes locally
+- `main` is green on GitHub
+- `CHANGELOG.md` reflects the release contents
+- `package.json` version is correct
+- `NPM_TOKEN` is configured in GitHub Actions secrets
+
+## Release Process
+
+1. update version and changelog if needed
+2. push the release-ready branch through the normal PR flow
+3. tag the release with `v*` such as `v0.1.0`
+4. let `.github/workflows/release.yml` publish to npm
+5. create or confirm the GitHub release notes
+
+## What This Repository Already Has
+
+- release workflow wiring
+- package verification in CI
+- changelog file
+- protected main branch
+
+## What Is Still Manual
+
+- deciding the first public version
+- creating the first release tag
+- ensuring npm credentials are present
+
+## Related Docs
+
+- [Usage Guide](./usage-guide.md)
+- [Governance and Branch Policy](./governance-guide.md)
+- [Changelog](../../CHANGELOG.md)
diff --git a/docs/en/usage-guide.md b/docs/en/usage-guide.md
index 2976ba6..3d5d188 100644
--- a/docs/en/usage-guide.md
+++ b/docs/en/usage-guide.md
@@ -1,12 +1,28 @@
 # Usage Guide
 
-## Installation
+## 1. Before You Start
+
+Today, `opencode-ceo` is repository-ready but not publicly released on npm yet.
+
+That means there are two different usage modes:
+
+- repository development and evaluation from this codebase
+- future npm installation after the first public release
+
+## 2. Local Setup
 
 ```bash
-npm install opencode-ceo
+bun install
+bun run ci:verify
 ```
 
-## Minimal Configuration
+If you plan to use GitHub delivery locally:
+
+```bash
+gh auth login
+```
+
+## 3. Minimal Configuration
 
 ```json
 {
@@ -21,7 +37,9 @@ npm install opencode-ceo
 }
 ```
 
-## Controlled Configuration
+Use this when you want the CEO agent to move through the full pipeline automatically.
+
+## 4. Controlled Configuration
 
 ```json
 {
@@ -47,26 +65,30 @@ npm install opencode-ceo
 }
 ```
 
-## Runtime Flow
+Use this when you want explicit human checkpoints before the plan, review, or delivery is accepted.
+
+## 5. Runtime Flow
 
-1. The `ceo` agent receives the task.
-2. The pipeline enters `intake` and moves through decomposition, implementation, review, test, and delivery.
-3. Artifacts, gates, decisions, and stage history are stored in SQLite under `.ceo/` at runtime.
-4. GitHub delivery tools can prepare a branch and open a PR when the repository is configured with a GitHub remote.
+1. `ceo` receives the task.
+2. The pipeline enters `intake` and advances through decomposition, implementation, review, test, and delivery.
+3. Gates, artifacts, stage history, and decisions are stored in SQLite under `.ceo/` at runtime.
+4. If the repository is GitHub-ready, delivery helpers can prepare a branch and open a pull request.
 
-## Recommended Local Workflow
+## 6. Day-To-Day Commands
 
 ```bash
-bun install
+bun run build
+bun run typecheck
+bun test
+bun run pack:check
 bun run ci:verify
-gh auth login
 ```
 
-## Troubleshooting
+## 7. Troubleshooting
 
 ### `bun install --frozen-lockfile` fails in CI
 
-Run `bun install` locally and commit the updated `bun.lock`.
+Run `bun install` locally and commit the updated `bun.lock` file.
 
 ### PR creation fails
 
@@ -78,10 +100,15 @@ Check all of the following:
 
 ### Delivery is blocked by gates
 
-Use a less restrictive `autonomyLevel`, or configure the relevant `gates` entry to `auto`.
+Use a less restrictive `autonomyLevel`, or change the relevant `gates` entry to `auto`.
+
+### The package is not available from npm
+
+That is expected until the first public release is published. Use the repository directly until then.
 
-## Related Docs
+## 8. Related Docs
 
-- `pull-request-guide.md`
-- `model-recommendations.md`
-- `../ARCHITECTURE.md`
+- [Pull Request Guide](./pull-request-guide.md)
+- [Model Recommendations](./model-recommendations.md)
+- [Release Guide](./release-guide.md)
+- [Architecture](../ARCHITECTURE.md)
diff --git a/docs/tr/kullanim-kilavuzu.md b/docs/tr/kullanim-kilavuzu.md
index eddd3ef..d7e14e8 100644
--- a/docs/tr/kullanim-kilavuzu.md
+++ b/docs/tr/kullanim-kilavuzu.md
@@ -1,12 +1,28 @@
 # Kullanim Kilavuzu
 
-## Kurulum
+## 1. Baslamadan Once
+
+Bugun icin `opencode-ceo` repo duzeyinde hazir, ancak npm uzerinden genel kullanim icin henuz yayinlanmis degil.
+
+Bu nedenle iki farkli kullanim modu var:
+
+- bu repo uzerinden yerel gelistirme ve deneme
+- ilk genel yayin sonrasi `npm install`
+
+## 2. Yerel Kurulum
 
 ```bash
-npm install opencode-ceo
+bun install
+bun run ci:verify
 ```
 
-## En Kucuk Konfigurasyon
+GitHub teslimat akisini yerelde kullanacaksaniz:
+
+```bash
+gh auth login
+```
+
+## 3. En Kucuk Konfigurasyon
 
 ```json
 {
@@ -21,7 +37,9 @@ npm install opencode-ceo
 }
 ```
 
-## Kontrollu Konfigurasyon
+Bunu, CEO ajaninin tum pipeline'i otomatik yuruttugu senaryolar icin kullanin.
+
+## 4. Kontrollu Konfigurasyon
 
 ```json
 {
@@ -47,22 +65,26 @@ npm install opencode-ceo
 }
 ```
 
-## Calisma Akisi
+Bunu, plan, review veya delivery oncesinde insan onayi istediginiz senaryolarda kullanin.
+
+## 5. Calisma Akisi
 
-1. `ceo` ajani gorevi alir.
-2. Pipeline intake, decompose, implement, review, test ve deliver asamalarindan gecer.
-3. Artifact, gate, decision ve stage gecmisi `.ceo/` altindaki SQLite state icinde tutulur.
-4. GitHub delivery araclari, repo dogru sekilde ayarlandiysa branch ve PR akisina kadar teslimat yapar.
+1. `ceo` gorevi alir.
+2. Pipeline `intake`, `decompose`, `implement`, `review`, `test` ve `deliver` asamalarindan gecer.
+3. Gate, artifact, stage gecmisi ve kararlar `.ceo/` altindaki SQLite state icinde tutulur.
+4. Repo GitHub icin hazirsa branch ve PR teslimati da otomatiklestirilebilir.
 
-## Onerilen Yerel Akis
+## 6. Guncelik Komutlar
 
 ```bash
-bun install
+bun run build
+bun run typecheck
+bun test
+bun run pack:check
 bun run ci:verify
-gh auth login
 ```
 
-## Sorun Giderme
+## 7. Sorun Giderme
 
 ### CI'da `bun install --frozen-lockfile` hatasi
 
@@ -79,3 +101,14 @@ Sunlari kontrol edin:
 ### Gate nedeniyle teslimat bloklaniyor
 
 Daha az kisitlayici bir `autonomyLevel` secin veya ilgili `gates` girdisini `auto` yapin.
+
+### Paket npm'de gorunmuyor
+
+Bu durum ilk genel yayin yapilana kadar normaldir. O zamana kadar repo uzerinden calisin.
+
+## 8. Ilgili Dokumanlar
+
+- [PR Kilavuzu](./pr-kilavuzu.md)
+- [Model Onerileri](./model-onerileri.md)
+- [Surum ve Yayin Rehberi](./surum-yayin-rehberi.md)
+- [Mimari](../ARCHITECTURE.md)
diff --git a/docs/tr/model-onerileri.md b/docs/tr/model-onerileri.md
index 4c7d996..2236ac9 100644
--- a/docs/tr/model-onerileri.md
+++ b/docs/tr/model-onerileri.md
@@ -2,6 +2,15 @@
 
 Bu rehber, `modelPreferences` ayarlarini pipeline asamalarina gore daha mantikli secmenize yardim eder.
 
+## Onerilen Baslangic Noktasi
+
+Kolay bir varsayilan istiyorsaniz:
+
+- `decompose` icin ulasabildiginiz en guclu akil yurutme modelini kullanin
+- `implement` icin kodlama odakli bir model secin
+- `review` gucunu `implement` seviyesinin altina dusurmeyin
+- tekrarli `test` dongulerinde daha hizli ve ucuz bir model kullanin
+
 ## Genel Kural
 
 - planlama ve inceleme icin yuksek akil yurutme modelleri kullanin
@@ -31,3 +40,8 @@ Bu rehber, `modelPreferences` ayarlarini pipeline asamalarina gore daha mantikli
 ```
 
 Bu isimleri kendi OpenCode ortaminda kullanabildiginiz model kimlikleri ile degistirin.
+
+## Ilgili Dokumanlar
+
+- [Kullanim Kilavuzu](./kullanim-kilavuzu.md)
+- [Surum ve Yayin Rehberi](./surum-yayin-rehberi.md)
diff --git a/docs/tr/pr-kilavuzu.md b/docs/tr/pr-kilavuzu.md
index 64efa9e..5cbded2 100644
--- a/docs/tr/pr-kilavuzu.md
+++ b/docs/tr/pr-kilavuzu.md
@@ -34,3 +34,9 @@ bun run ci:verify
 - history okunabilir ve odakli kalsin
 - tek buyuk PR yerine kucuk ve bagimsiz PR'lari tercih edin
 - acil durum disinda branch protection'i baypas etmeyin
+
+## Ilgili Dokumanlar
+
+- [Yonetsim ve Branch Politikasi](./yonetisim-rehberi.md)
+- [Kullanim Kilavuzu](./kullanim-kilavuzu.md)
+- [Katki Rehberi](../../CONTRIBUTING.md)
diff --git a/docs/tr/surum-yayin-rehberi.md b/docs/tr/surum-yayin-rehberi.md
new file mode 100644
index 0000000..eda7898
--- /dev/null
+++ b/docs/tr/surum-yayin-rehberi.md
@@ -0,0 +1,44 @@
+# Surum ve Yayin Rehberi
+
+## Guncel Yayin Durumu
+
+- npm paketi: henuz yayinlanmadi
+- GitHub release: henuz olusturulmadi
+- release workflow: `.github/workflows/release.yml` icinde hazir
+
+## Ilk Yayin Oncesi Kontrol Listesi
+
+Sunlarin tam oldugundan emin olun:
+
+- `bun run ci:verify` yerelde geciyor
+- GitHub uzerinde `main` yesil
+- `CHANGELOG.md` yayin icerigini anlatiyor
+- `package.json` versiyonu dogru
+- GitHub Actions secrets icinde `NPM_TOKEN` tanimli
+
+## Yayin Akisi
+
+1. gerekirse versiyon ve changelog guncellenir
+2. release'e hazir degisiklik normal PR akisindan gecirilir
+3. `v0.1.0` gibi `v*` etiketi olusturulur
+4. `.github/workflows/release.yml` npm yayini yapar
+5. GitHub release notlari olusturulur veya dogrulanir
+
+## Bu Repo'da Hazir Olanlar
+
+- release workflow baglantisi
+- CI icinde paket dogrulamasi
+- changelog dosyasi
+- korumali `main` branch
+
+## Hala Manuel Olanlar
+
+- ilk genel surum kararinin verilmesi
+- ilk release tag'inin olusturulmasi
+- npm kimlik bilgilerinin hazir olmasi
+
+## Ilgili Dokumanlar
+
+- [Kullanim Kilavuzu](./kullanim-kilavuzu.md)
+- [Yonetsim ve Branch Politikasi](./yonetisim-rehberi.md)
+- [Degisiklik Gunlugu](../../CHANGELOG.md)
diff --git a/docs/tr/yonetisim-rehberi.md b/docs/tr/yonetisim-rehberi.md
new file mode 100644
index 0000000..3279c86
--- /dev/null
+++ b/docs/tr/yonetisim-rehberi.md
@@ -0,0 +1,36 @@
+# Yonetsim ve Branch Politikasi
+
+## `main` Branch Koruma Kurallari
+
+Repo, `main` branch'ini kontrollu tutacak sekilde ayarlandi:
+
+- zorunlu kontroller: `quality`, `tests`, `package`
+- lineer history zorunlu
+- force-push kapali
+- merge oncesi konusma cozum zorunlulugu var
+- admin enforcement aktif
+
+## Pratik Merge Politikasi
+
+- `main` hedefli degisiklikler icin PR acin
+- PR'lari kucuk ve okunabilir tutun
+- zorunlu kontroller kirmiziyken merge etmeyin
+- acik review konusmalarini merge oncesi kapatin
+
+## Yonetsimi Destekleyen Otomasyon
+
+- CI workflow: `.github/workflows/ci.yml`
+- release workflow: `.github/workflows/release.yml`
+- Dependabot: `.github/dependabot.yml`
+- PR sablonu: `.github/PULL_REQUEST_TEMPLATE.md`
+
+## Guncel Sinirlar
+
+- ilk genel release henuz olusturulmadi
+- npm yayini henuz yapilmadi
+
+## Ilgili Dokumanlar
+
+- [PR Kilavuzu](./pr-kilavuzu.md)
+- [Surum ve Yayin Rehberi](./surum-yayin-rehberi.md)
+- [Guvenlik](../../SECURITY.md)
diff --git a/package.json b/package.json
index 0d4925e..21b95fb 100644
--- a/package.json
+++ b/package.json
@@ -11,15 +11,27 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/vaur94/opencode-ceo"
+    "url": "git+https://github.com/vaur94/opencode-ceo.git"
+  },
+  "homepage": "https://github.com/vaur94/opencode-ceo#readme",
+  "bugs": {
+    "url": "https://github.com/vaur94/opencode-ceo/issues"
   },
   "author": "opencode-ceo contributors",
   "license": "MIT",
+  "engines": {
+    "bun": ">=1.3.10"
+  },
   "module": "./dist/index.js",
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
     "dist/",
     "README.md",
+    "README.tr.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "exports": {