docs(i18n): copy-edit the English to newspaper style

CONTRIBUTING.md

@@ -47,6 +47,31 @@ npm run check   # astro check (type-check) — must pass
 `npm run build` fetches from `api.github.com`; export `GITHUB_TOKEN` locally
 if you hit rate limits (CI passes its built-in token).
 
+## Prose style
+
+Site copy is edited to newspaper style. The register is the product's — dry,
+declarative, honest result first — and headlines like "Gates that refuse to
+flatter" are doing real work. The rules below are about legibility, not voice.
+
+- **One dash-set aside per sentence.** Past that, split the sentence.
+- **Sentences under ~35 words.** Longer only when the length is doing something
+  a break would lose, such as a parallel enumeration.
+- **Gloss jargon on first use, per page.** Each page is a standalone article for
+  a reader arriving from search: `PBO/CSCV`, basis points, "per leg", "taker
+  fee" and "fails closed" all get expanded where they first appear on a page.
+- **Figures:** `about`, not `~`, in prose; keep the tilde for tables and
+  parentheses. Spell out one through nine, figures from 10 up.
+- **`keel` is always lowercase**, including sentence-initial and in `<title>`.
+- **Curly quotes** in prose; straight quotes only inside code.
+- **CLI literals keep their exact form** — `GO-LIVE`, `TRAIN-MORE`, never
+  `TRAIN MORE`.
+- **Spelling is US** (`summarize`, `practiced`).
+- **Meta descriptions stay under 160 characters** so they do not truncate in
+  search results.
+
+Arabic follows Modern Standard Arabic, with one settled rendering per technical
+term — see the terminology table in #34.
+
 ## Honesty rules (FR-9)
 
 No profit claims, no testimonial walls, results stated exactly as the engine

src/i18n/guides/content.ts

@@ -122,7 +122,7 @@ export const guides: Guide[] = [
         title: "Step 4 — Read the report honestly",
         body: [
           "The report ends with GO-LIVE or TRAIN-MORE, naming every gate and its numbers: performance floors, the 100-trade sample floor, the overfitting check.",
-          "On the default rules it will very likely say TRAIN MORE. That is the engine working, not broken — keel refuses to flatter a backtest, and no shipped rule family is net-positive at the taker fee actually paid. The honesty is the feature.",
+          "On the default rules it will very likely say TRAIN-MORE. That is the engine working, not broken: keel refuses to flatter a backtest, and no shipped rule family is net positive at the taker fee actually paid. The honesty is the feature.",
         ],
       },
       {
@@ -163,12 +163,12 @@ export const guides: Guide[] = [
         code: "keel agent",
         shot: "/get-started/tui-rules.png",
         shotCaption:
-          "The Rules console (4): the tried-vs-used ledger — every rule with its lifecycle status. candidate → paper → live is the only road to live trading.",
+          "The Rules console (4): the lifecycle ledger — every rule with the stage it has reached. candidate → paper → live is the only road to live trading.",
       },
       {
         title: "Step 3 — Confirm every order",
         body: [
-          "By default the agent previews each order and asks you at the terminal; headless, it declines. keel autonomy on changes who is asked — never what is allowed. For the paper profile, answering prompts is the point: watch what the rails veto and why.",
+          "By default the agent previews each order and asks you at the terminal. Running headless, with no one to ask, it declines. keel autonomy on changes who is asked — never what is allowed. For the paper profile, answering prompts is the point: watch what the rails veto and why.",
         ],
       },
       {
@@ -238,7 +238,7 @@ export const guides: Guide[] = [
       {
         title: "Where this leads",
         body: [
-          "With attestations recorded, a rule promoted through its gates, and the go-live runbook followed, the supervised first live order is the same confirm prompt you practised in paper — with real consequences. Read the go-live runbook before that day.",
+          "With attestations recorded, a rule promoted through its gates, and the go-live runbook followed, the supervised first live order is the same confirm prompt you practiced in paper — with real consequences. Read the go-live runbook before that day.",
         ],
       },
     ],

src/i18n/pages/about.ts

@@ -24,7 +24,7 @@ export interface AboutContent {
 
 export const about: LocalizedPage<AboutContent> = {
   en: {
-    rev: "2026-08-20.1",
+    rev: "2026-08-20.2",
     title: "About keel — Name, License, keel.sh & KEEL FAQ",
     description:
       "Who runs keeltrading.com, licensing, and the brand FAQ — why this keel is not Kubernetes Keel (keel.sh) nor Keel Infrastructure (KEEL).",
@@ -44,13 +44,13 @@ export const about: LocalizedPage<AboutContent> = {
       {
         question: "Is this the Kubernetes project called Keel?",
         answer: [
-          "No. There is an established Kubernetes deployment tool named Keel at keel.sh, and it currently owns the bare-\"keel\" search results. This project — keel by CodeGate Software — is unrelated to it: no shared code, history, or people. We call the project \"keel trading\" where ambiguity would mislead, and this site exists partly to make that distinction easy to find.",
+          "No. There is an established Kubernetes deployment tool named Keel at keel.sh, and it currently owns the bare-“keel” search results. This project — keel by CodeGate Software — is unrelated to it: no shared code, history, or people. We call the project “keel trading” where ambiguity would mislead, and this site exists partly to make that distinction easy to find.",
         ],
       },
       {
         question: "Is this Keel Infrastructure, the KEEL stock?",
         answer: [
-          "No. A Nasdaq-listed bitcoin-mining company (formerly Bitfarms) trades under the ticker KEEL, so a search for \"keel trading\" or \"keel crypto\" may show its stock chart near these results. It has no connection to this project. This keel is an open-source compliance engine by CodeGate Software — if you landed on keeltrading.com, you are in the right place.",
+          "No. A Nasdaq-listed bitcoin-mining company (formerly Bitfarms) trades under the ticker KEEL, so a search for “keel trading” or “keel crypto” may show its stock chart near these results. It has no connection to this project. This keel is an open-source compliance engine by CodeGate Software — if you landed on keeltrading.com, you are in the right place.",
         ],
       },
       {
@@ -85,7 +85,7 @@ export const about: LocalizedPage<AboutContent> = {
         question: "Why is keel open source — and free?",
         answer: [
           "Because keel's entire value is auditability. A compliance engine you cannot inspect is exactly the “trust me” model keel exists to replace: closed screening tools ask you to believe their verdicts; keel publishes the machinery and the rulings it enforces, with sources. Openness is not a marketing choice bolted on — it is the product.",
-          "And to be precise about “free”: the engine is free by license, not by trial. Apache-2.0 cannot be un-free'd — that copy of the license ships with every version.",
+          "And to be precise about “free”: the engine is free by license, not by trial. Apache-2.0 cannot be revoked: a copy of the license ships with every version.",
         ],
       },
       {
@@ -107,8 +107,8 @@ export const about: LocalizedPage<AboutContent> = {
   },
 
   ar: {
-    rev: "2026-08-20.1",
-    translatedFromRev: "2026-08-20.1",
+    rev: "2026-08-20.2",
+    translatedFromRev: "2026-08-20.2",
     title: "حول كيل — الاسم والترخيص وأسئلة keel.sh وKEEL",
     description:
       "مَن يُشغّل keeltrading.com، والتراخيص، والأسئلة الشائعة عن الاسم — ولماذا ليس هذا كيلَ Kubernetes‏ (keel.sh) ولا شركةَ Keel Infrastructure‏ (KEEL).",
@@ -191,8 +191,8 @@ export const about: LocalizedPage<AboutContent> = {
   },
 
   fr: {
-    rev: "2026-08-20.1",
-    translatedFromRev: "2026-08-20.1",
+    rev: "2026-08-20.2",
+    translatedFromRev: "2026-08-20.2",
     title: "À propos de keel — nom, licence et FAQ keel.sh & KEEL",
     description:
       "Qui édite keeltrading.com, les licences, et la FAQ de la marque — pourquoi ce keel n'est ni le Keel de Kubernetes (keel.sh) ni Keel Infrastructure (KEEL).",

src/i18n/pages/community.ts

@@ -26,14 +26,14 @@ const SLUG_BASE = "https://github.com/CodeGateSoftware/keel/discussions/categori
 
 export const community: LocalizedPage<CommunityContent> = {
   en: {
-    rev: "2026-08-19.2",
+    rev: "2026-08-20.2",
     title: "keel Community on GitHub Discussions",
     description:
       "Questions, ideas, polls, and classification debate happen on GitHub Discussions. The site only reads and links — interaction stays where the project lives.",
     intro: [
       "Everything community-shaped happens on GitHub Discussions — posting, voting, polling, answering. This website deliberately has none of that: it reads and links, because that is where the project, its history, and its moderation already live.",
     ],
-    note: "One category deserves a special mention: Compliance & classification. \"Should X be treated this way?\" is a question, not a bug — and there is a place for it.",
+    note: "One category deserves a special mention: Compliance & classification. “Should X be treated this way?” is a question, not a bug — and there is a place for it.",
     categories: [
       {
         name: "Announcements",
@@ -43,7 +43,7 @@ export const community: LocalizedPage<CommunityContent> = {
       {
         name: "Compliance & classification",
         slug: "compliance-classification",
-        description: "The \"should X be treated this way\" conversations — classification discussion is a question, not a bug, and must not be triaged as one.",
+        description: "The “should X be treated this way” conversations — classification discussion is a question, not a bug, and must not be triaged as one.",
       },
       {
         name: "Ideas",
@@ -74,8 +74,8 @@ export const community: LocalizedPage<CommunityContent> = {
   },
 
   ar: {
-    rev: "2026-08-19.2",
-    translatedFromRev: "2026-08-19.2",
+    rev: "2026-08-20.2",
+    translatedFromRev: "2026-08-20.2",
     title: "مجتمع كيل على نقاشات GitHub",
     description:
       "الأسئلة والأفكار واستطلاعات الرأي ونقاش التصنيف تجري في نقاشات GitHub. وهذا الموقع يقرأ ويربط فقط — ويبقى التفاعل حيث يعيش المشروع.",
@@ -123,8 +123,8 @@ export const community: LocalizedPage<CommunityContent> = {
   },
 
   fr: {
-    rev: "2026-08-20.1",
-    translatedFromRev: "2026-08-19.2",
+    rev: "2026-08-20.2",
+    translatedFromRev: "2026-08-20.2",
     title: "La communauté keel — sur GitHub, par choix",
     description:
       "Questions, idées, sondages et débats de classification ont lieu dans les Discussions GitHub de keel. Ce site se contente de lire et de renvoyer : l'échange reste là où vit le projet.",

src/i18n/pages/compare.ts

@@ -40,45 +40,45 @@ export const compareColumns = [
 
 export const compare: LocalizedPage<CompareContent> = {
   en: {
-    rev: "2026-08-20.4",
+    rev: "2026-08-20.5",
     title: "How keel Compares to Other Trading Bots",
     description:
-      "keel compared with Freqtrade, Jesse, and Hummingbot: license, focus, strategy gates, and the compliance machinery none of them carry — structural facts from public repositories.",
+      "keel compared with Freqtrade, Jesse and Hummingbot: license, focus, strategy gates, and the compliance machinery none of them carry.",
     intro: [
       "Freqtrade, Jesse, and Hummingbot are established, capable open-source trading bots — far more mature than keel, with communities orders of magnitude larger. If you want general algorithmic trading with the widest exchange coverage, they are the better answer.",
       "This page states, factually and from public repositories, where keel differs: keel is not a better trading bot — it is a different thing, an enforcement engine for Shariah compliance you supply.",
     ],
     tableTitle: "Structural comparison",
     footnote:
-      "Facts from each project's public repository, August 2026. Community scale (GitHub stars, same date): Freqtrade ~53k, Hummingbot ~19.5k, Jesse ~8.3k — keel just launched. The Cost row was verified from each project's own site on 2026-08-20; Jesse's plugin pricing changes often — re-check at jesse.trade/pricing. Freqtrade, Jesse, Hummingbot, and QuantCrawler are projects of their maintainers; their names appear here solely to identify them. Alpaca is a brokerage, not a bot — keel ships a broker adapter for it under the venue port.",
+      "Facts from each project's public repository, August 2026. Community scale, measured in GitHub stars on the same date: Freqtrade about 53,000, Hummingbot about 19,500, Jesse about 8,300. keel has just launched. The Cost row was verified from each project's own site on 2026-08-20; Jesse's plugin pricing changes often, so re-check it at jesse.trade/pricing. Freqtrade, Jesse, Hummingbot and QuantCrawler are projects of their maintainers, and their names appear here solely to identify them. Alpaca is a brokerage, not a bot: keel ships a broker adapter for it under the venue port.",
     readingTitle: "How to read this",
     reading: [
       "Every project here backtests strategies and can trade crypto. The differences that matter are structural: what the engine refuses to do, what it requires before a rule may trade live money, and whether compliance is machinery or nothing at all.",
       "None of the comparison cells are value judgments. Freqtrade's breadth, Jesse's research workflow, and Hummingbot's market-making depth are real strengths — keel has none of them, by design.",
     ],
     paidTitle: "What about paid services?",
     paidBody: [
-      "QuantCrawler is the kind of paid service many retail traders meet first: $9.99/month after a 30-day free trial (verified 2026-08-20). It relays TradingView webhook alerts to your broker and copies trades across accounts — ten broker integrations, Coinbase among them, with a futures and prop-firm focus. It is closed-source and cloud-hosted: you connect your broker credentials to their platform, and execution runs on their servers.",
+      "QuantCrawler is the kind of paid service many retail traders meet first: $9.99 a month after a 30-day free trial (verified 2026-08-20). It relays TradingView webhook alerts to your broker and copies trades across accounts — ten broker integrations, Coinbase among them, with a futures and prop-firm focus. It is closed-source and cloud-hosted: you connect your broker credentials to their platform, and execution runs on their servers.",
       "keel is the opposite trade-off. Nothing hosted, nothing closed: the engine runs on your machine, your keys never leave it, and no rule may touch live money before clearing the promotion gate. What keel does not have is QuantCrawler's broker breadth or its TradingView-first workflow — if that is what you need, theirs is the fitting answer, at the price of entrusting a service with your credentials. Like the bots above, it carries no compliance machinery; that difference is keel's reason to exist.",
     ],
     venuesTitle: "Which venues, and why",
     venuesBody: [
-      "keel's Coinbase adapter is the live-proven reference: attested spot screening, real orders, the whole gauntlet exercised in production. Alpaca is wired for deployment on the equities side — the same enforcement, paper-first, with session-aware market clocks. The Robinhood adapter ships in the repository as an optional dev venue, deliberately outside deployments until its live-path prerequisites close.",
-      "What keel declines categorically: futures, margin, shorting, and derivatives of any kind — long-only spot is the whole surface, by fiqh posture and by design. Venue breadth is deliberately not chased; every new venue is a capability-verified adapter decision, not a growth metric.",
+      "keel's Coinbase adapter is the live-proven reference: attested spot screening, real orders, the whole gauntlet run in production. Alpaca is wired for deployment on the equities side — the same enforcement, paper-first, with session-aware market clocks. The Robinhood adapter ships in the repository as an optional dev venue, deliberately outside deployments until its live-path prerequisites close.",
+      "What keel declines categorically: futures, margin, shorting, and derivatives of any kind — long-only spot is the whole surface, by fiqh posture and by design. We deliberately do not chase venue breadth. Every new venue is an adapter decision, taken once its capabilities are verified, and never a growth metric.",
     ],
     catchLink: "Why is keel free when the others charge subscriptions? The honest answer is on the About page.",
     wontDoTitle: "What keel will not do",
     wontDo: [
       "Chase exchange coverage: Coinbase is the live-proven reference and Alpaca is wired for equities paper; the Robinhood adapter ships optional/dev, deliberately outside deployments.",
       "Trade anything but long-only spot: no leverage, no shorting, no derivatives.",
       "Promote a rule on backtest brilliance alone: the overfitting check (PBO/CSCV) can veto it.",
-      "Promise profit: no shipped rule family is net-positive at the taker fee actually paid, and the site says so on its front page.",
+      "Promise profit: no shipped rule family is net positive at the taker fee actually paid, and the site says so on its front page.",
     ],
   },
 
   ar: {
-    rev: "2026-08-20.4",
-    translatedFromRev: "2026-08-20.4",
+    rev: "2026-08-20.5",
+    translatedFromRev: "2026-08-20.5",
     title: "مقارنة كيل ببوتات التداول الأخرى",
     description:
       "مقارنة كيل بـ Freqtrade وJesse وHummingbot: الترخيص والغرض وبوابات الترقية وآلياتُ الامتثال التي لا يحملها أيٌّ منها — وقائعُ بنيويةٌ من المستودعات العمومية.",
@@ -115,8 +115,8 @@ export const compare: LocalizedPage<CompareContent> = {
   },
 
   fr: {
-    rev: "2026-08-20.4",
-    translatedFromRev: "2026-08-20.4",
+    rev: "2026-08-20.5",
+    translatedFromRev: "2026-08-20.5",
     title: "Comparer keel aux autres bots de trading",
     description:
       "keel face à Freqtrade, Jesse et Hummingbot : licence, finalité, verrous de promotion et la machinerie de conformité qu'aucun d'eux n'embarque — des faits structurels tirés des dépôts publics.",
@@ -340,7 +340,7 @@ export const compareRows = (locale: "en" | "ar" | "fr"): CompareRow[] => {
     {
       label: "Shariah compliance machinery",
       values: [
-        "Attested fail-closed screening + 18 un-overridable rails (incl. qabd)",
+        "Attested screening that fails closed + 18 rails no order can skip (including qabd)",
         "Not built in",
         "Not built in",
         "Not built in",