From 02bce8e9ad0b5ee040017fbd7b4dec6721f8a0c0 Mon Sep 17 00:00:00 2001
From: Abdullah Kaya <abdullahk.0634@gmail.com>
Date: Sat, 1 Aug 2026 03:15:19 +0300
Subject: [PATCH] docs: correct the deployment story in the README

The README claimed "Any push to the `main` branch will trigger an automatic
build and deployment". That has not been true since deployment was gated on
`release: published`: pushing to `main` runs ci.yml, which verifies and stops.
Anyone following the README would push, watch a green check, and wonder why
production had not moved. docs/TOOLCHAIN.md had already flagged the drift.

- Describe both workflows and what each one does, so the split between
  verification and deployment is explicit
- Spell out the actual release path: land via pull request (branch protection
  requires it), `chore(release): X.Y.Z`, tag, publish the release
- Point at docs/TOOLCHAIN.md for the full reference
- Document `bun run gate`, which the pre-push hook and CI both enforce but the
  README never mentioned
- Fix the live site link: the canonical host is libredb.org, and
  libredb.github.io 301-redirects to it

TOOLCHAIN.md's closing note recorded this inconsistency as outstanding; it now
records it as resolved, so the two documents agree.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md         | 32 +++++++++++++++++++++++++++++---
 docs/TOOLCHAIN.md | 10 ++++++----
 2 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 3f03057..b00aa20 100644
--- a/README.md
+++ b/README.md
@@ -22,17 +22,43 @@ bun run build
 
 # Preview production build
 bun preview
+
+# Full verification: typecheck, format, lint, dead-code, tests
+bun run gate
 ```
 
+`bun run gate` is the bar every change must clear. The `pre-push` hook runs it
+locally and CI runs the same steps, so a failing gate never reaches `main`.
+
 ## Deployment
 
-This site is deployed to GitHub Pages via GitHub Actions.
+This site is deployed to GitHub Pages via GitHub Actions, in two deliberately
+separate workflows:
+
+| Workflow     | Trigger                                   | What it does                                                                     |
+| ------------ | ----------------------------------------- | -------------------------------------------------------------------------------- |
+| `ci.yml`     | pull request, push to `main`              | Verifies only — gate, secret scan, dependency audit, build. **Does not deploy.** |
+| `deploy.yml` | `release: published` (or manual dispatch) | Builds and deploys to GitHub Pages.                                              |
+
+**Pushing to `main` does not deploy.** Going live means tagging a version and
+publishing a GitHub release:
+
+```bash
+# 1. Land the change on main (branch protection requires a pull request)
+# 2. Bump the version in package.json — commit as `chore(release): X.Y.Z`
+# 3. Tag that commit and publish the release
+git tag vX.Y.Z && git push origin vX.Y.Z
+gh release create vX.Y.Z --verify-tag --title "vX.Y.Z — short summary"
+```
+
+Publishing the release is what triggers `deploy.yml`.
 
-Any push to the `main` branch will trigger an automatic build and deployment.
+See [`docs/TOOLCHAIN.md`](docs/TOOLCHAIN.md) for the full toolchain and CI/CD
+reference.
 
 ## Links
 
-- **Live Site**: https://libredb.github.io
+- **Live Site**: https://libredb.org
 - **Main Project**: https://github.com/libredb/libredb-studio
 - **Live Demo**: https://app.libredb.org
 - **LinkedIn**: https://www.linkedin.com/company/libredb
diff --git a/docs/TOOLCHAIN.md b/docs/TOOLCHAIN.md
index c2a9956..11d1667 100644
--- a/docs/TOOLCHAIN.md
+++ b/docs/TOOLCHAIN.md
@@ -294,8 +294,10 @@ git push    ──────►  pre-push        ─────────
 
 ---
 
-## Ek: Tespit Edilen Tutarsızlık
+## Ek: Giderilen Tutarsızlık
 
-`README.md` hâlâ *"Any push to the `main` branch will trigger an automatic build
-and deployment"* diyor. Bu **güncel değil** — gerçek davranış `deploy.yml`'de
-`release: published` ile kapılı. README'nin Deployment bölümü güncellenmelidir.
+`README.md` bir süre *"Any push to the `main` branch will trigger an automatic
+build and deployment"* diyordu; gerçek davranış ise `deploy.yml`'de
+`release: published` ile kapılıdır. README'nin Deployment bölümü, iki
+workflow'un ayrımını ve tag + release akışını anlatacak şekilde güncellendi —
+artık bu belgeyle tutarlı.