HugoMachadoRodrigues · HugoMachadoRodrigues · May 9, 2026 · May 9, 2026 · May 9, 2026
diff --git a/CITATION.cff b/CITATION.cff
@@ -18,7 +18,7 @@ authors:
     email: "rodrigues.machado.hugo@gmail.com"
     affiliation: "Universidade Federal Rural do Rio de Janeiro (UFRRJ), Departamento de Solos"
     orcid: "https://orcid.org/0000-0002-8070-8126"
-version: "0.9.95"
+version: "0.9.96"
 date-released: "2026-05-09"
 doi: "10.5281/zenodo.19930112"
 license: "MIT"
@@ -50,7 +50,7 @@ preferred-citation:
       given-names: "Hugo"
       email: "rodrigues.machado.hugo@gmail.com"
       orcid: "https://orcid.org/0000-0002-8070-8126"
-  version: "0.9.95"
+  version: "0.9.96"
   year: 2026
   doi: "10.5281/zenodo.19930112"
   url: "https://github.com/HugoMachadoRodrigues/soilKey"
@@ -74,7 +74,7 @@ references:
       city: "Washington, DC"
     url: "https://www.nrcs.usda.gov/sites/default/files/2022-09/Keys-to-Soil-Taxonomy.pdf"
   - type: book
-    title: "Sistema Brasileiro de Classificação de Solos, 5ª edição revista e ampliada"
+    title: "Brazilian Soil Classification System (SiBCS), 5th revised and extended edition"
     authors:
       - family-names: "Santos"
         given-names: "H. G."
@@ -90,7 +90,7 @@ references:
         given-names: "M. R."
       - family-names: "Almeida"
         given-names: "J. A. de"
-      - family-names: "Araújo Filho"
+      - family-names: "Araujo Filho"
         given-names: "J. C. de"
       - family-names: "Oliveira"
         given-names: "J. B. de"
@@ -99,4 +99,140 @@ references:
     year: 2018
     publisher:
       name: "Embrapa"
-      city: "Brasília"
+      city: "Brasilia"
+  - type: article
+    title: "SmartSolos Expert: an expert system for Brazilian soil classification"
+    authors:
+      - family-names: "Vaz"
+        given-names: "G. J."
+      - family-names: "Silva Neto"
+        given-names: "L. de F. da"
+      - family-names: "Barbedo"
+        given-names: "J. G. A."
+    journal: "Smart Agricultural Technology"
+    volume: 10
+    start: 100735
+    year: 2025
+    month: 3
+    doi: "10.1016/j.atech.2024.100735"
+    notes: >
+      The SmartSolos Expert REST API at agroapi.cnptia.embrapa.br is
+      wrapped by classify_via_smartsolos_api() so soilKey users can
+      cross-validate the local SiBCS classifier against the
+      authoritative Embrapa-hosted reference. Cite this article when
+      using the cross-validation workflow.
+    url: "https://www.agroapi.cnptia.embrapa.br/store/apis/info?name=SmartSolosExpert&version=v1&provider=agroapi"
+  - type: conference-paper
+    title: "Uma API para a classificacao de solos do Brasil"
+    authors:
+      - family-names: "Vaz"
+        given-names: "G. J."
+      - family-names: "Silva Neto"
+        given-names: "L. de F. da"
+      - family-names: "Lima"
+        given-names: "R. N."
+      - family-names: "Oliveira"
+        given-names: "S. R. de M."
+    collection-title: "Anais do 12 Congresso Brasileiro de Agroinformatica"
+    conference:
+      name: "12 SBIAGRO Brazilian Conference on Agro-Informatics"
+      city: "Indaiatuba"
+    year: 2019
+    start: 63
+    end: 72
+    publisher:
+      name: "SBIAGRO"
+      city: "Ponta Grossa"
+    notes: >
+      The original announcement paper for the SmartSolos Expert
+      REST API. Cite this together with the 2025 journal article
+      when using soilKey's classify_via_smartsolos_api() bridge.
+  - type: data
+    title: "Brazilian soil data for taxonomic classification"
+    authors:
+      - family-names: "Vaz"
+        given-names: "G. J."
+      - family-names: "Silva Jr"
+        given-names: "A. F."
+      - family-names: "Silva Neto"
+        given-names: "L. de F. da"
+    year: 2023
+    version: "V1"
+    publisher:
+      name: "Redape (Embrapa Research Data Repository)"
+    doi: "10.48432/PYKKA7"
+    notes: >
+      The 96-profile curated GeoTab dataset bundled with soilKey via
+      load_redape_pedons() and benchmark_redape(). Pedologists
+      hand-reviewed every profile, making the dataset a gold-standard
+      benchmark for classify_sibcs() and classify_via_smartsolos_api().
+      Cite this DOI when reporting Redape benchmark numbers.
+  - type: report
+    title: "Africa Soil Profiles Database, Version 1.2"
+    authors:
+      - family-names: "Leenaars"
+        given-names: "J. G. B."
+      - family-names: "van Oostrum"
+        given-names: "A. J. M."
+      - family-names: "Ruiperez Gonzalez"
+        given-names: "M."
+    year: 2014
+    institution:
+      name: "ISRIC -- World Soil Information"
+      city: "Wageningen"
+    number: "ISRIC Report 2014/01"
+    url: "https://isric.org/projects/africa-soil-profiles-database-afsp"
+    notes: >
+      The Africa Soil Profiles (AfSP) database consumed by
+      benchmark_afsp() and load_afsp_pedons(). The bundled cache
+      ships ~120 stratified pedons. Note: AfSP is from ISRIC and is
+      DISTINCT from AfSIS (Africa Soil Information Service); soilKey
+      uses only AfSP, not AfSIS.
+  - type: report
+    title: "LUCAS 2018 SOIL Component: sampling intensity, harmonisation and procedures for the collection of soil samples"
+    authors:
+      - family-names: "Fernandez-Ugalde"
+        given-names: "O."
+      - family-names: "Scarpa"
+        given-names: "S."
+      - family-names: "Orgiazzi"
+        given-names: "A."
+      - family-names: "Panagos"
+        given-names: "P."
+      - family-names: "Van Liedekerke"
+        given-names: "M."
+      - family-names: "Marechal"
+        given-names: "A."
+      - family-names: "Jones"
+        given-names: "A."
+    year: 2022
+    institution:
+      name: "European Commission, Joint Research Centre"
+      city: "Ispra"
+    number: "JRC Technical Report 130218"
+    doi: "10.2760/215013"
+    notes: >
+      The canonical data report for the LUCAS-SOIL-2018 dataset
+      consumed by benchmark_lucas_2018() and load_lucas_pedons().
+      Cite this when reporting LUCAS-based numbers; the Orgiazzi
+      et al. 2018 EJSS paper is the dataset's review companion.
+  - type: article
+    title: "LUCAS Soil, the largest expandable soil dataset for Europe: a review"
+    authors:
+      - family-names: "Orgiazzi"
+        given-names: "A."
+      - family-names: "Ballabio"
+        given-names: "C."
+      - family-names: "Panagos"
+        given-names: "P."
+      - family-names: "Jones"
+        given-names: "A."
+      - family-names: "Fernandez-Ugalde"
+        given-names: "O."
+    journal: "European Journal of Soil Science"
+    volume: 69
+    issue: 1
+    start: 140
+    end: 153
+    year: 2018
+    doi: "10.1111/ejss.12499"
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,7 +1,7 @@
 Package: soilKey
 Type: Package
 Title: Automated Soil Profile Classification per WRB 2022, SiBCS 5 and USDA Soil Taxonomy 13
-Version: 0.9.95
+Version: 0.9.96
 Date: 2026-05-09
 Authors@R:
     person("Hugo", "Rodrigues",

diff --git a/NEWS.md b/NEWS.md
@@ -1,3 +1,114 @@
+# soilKey 0.9.96 (2026-05-09)
+
+The "**README full English rewrite + SmartSolos / Vaz citation pass**"
+release. Pure docs / no R code change. Brings the package
+documentation to a CRAN-submission-ready, fully internationalised,
+clearly status-tagged state.
+
+## README overhaul
+
+\itemize{
+  \item All Portuguese prose translated to English. Class names from
+        SiBCS / WRB / USDA appear as canonical taxonomic labels
+        (deliberate; they are the published nomenclature) but every
+        explanatory sentence is in English.
+  \item New "Status at a glance" table at the top of the README
+        with explicit \emph{shipped / in progress / idea-roadmap}
+        markers for every domain (WRB / SiBCS / USDA hierarchies,
+        side modules, and tooling). Lets readers see what's in v0.9.96
+        without scrolling through changelogs.
+  \item "What's new" section refreshed to summarise the v0.9.81 ->
+        v0.9.96 release series with the post-v0.9.95 cumulative
+        empirical lift table.
+  \item References section expanded to enumerate every benchmark
+        dataset's canonical citation (WRB book, SiBCS book, KST 13ed,
+        OSSL paper, WoSIS paper, AfSP report, LUCAS paper, NCSS-tech
+        \code{aqp}, plus the new SmartSolos / Redape citations).
+  \item "Citing" section explicitly documents which upstream works
+        to cite when using the package's specific entry points
+        (\code{classify_via_smartsolos_api}, \code{benchmark_redape},
+        \code{load_redape_pedons}).
+}
+
+## External-dataset citation pass
+
+In addition to the SmartSolos / Vaz et al. citations (next section),
+v0.9.96 explicitly cites the canonical sources of every external
+dataset \code{soilKey} consumes:
+
+\itemize{
+  \item \strong{AfSP (Africa Soil Profiles Database, ISRIC)} --
+        Leenaars, van Oostrum & Ruiperez Gonzalez (2014). Now in
+        \code{inst/CITATION}, \code{CITATION.cff} \code{references:},
+        and the README References list with an explicit note that
+        soilKey uses AfSP and \emph{not} the separate AfSIS (Africa
+        Soil Information Service) project.
+  \item \strong{LUCAS-SOIL-2018 (EU JRC)} -- both the data report
+        (Fernandez-Ugalde et al. 2022, JRC TR 130218,
+        \code{doi:10.2760/215013}) AND the review paper
+        (Orgiazzi et al. 2018, EJSS 69(1):140-153,
+        \code{doi:10.1111/ejss.12499}). Previous releases cited
+        only the review.
+  \item Existing citations refreshed: SoilGrids, WoSIS, OSSL,
+        KSSL, NCSS-tech \code{aqp}, IUSS WRB 2022, KST 13ed,
+        SiBCS 5 (translated title for the international README).
+}
+
+\code{citation("soilKey")} now renders 7 BibTeX entries: the package
++ 3 Vaz et al. works (SmartSolos journal, SmartSolos conference,
+Redape data) + AfSP + LUCAS data report + LUCAS review.
+
+## SmartSolos Expert / Vaz et al. citation pass
+
+soilKey's \code{classify_via_smartsolos_api()} bridge wraps Embrapa's
+authoritative SmartSolos Expert REST API (Vaz et al. 2025) so users
+can cross-validate the local SiBCS classifier against the same
+PROLOG implementation that backs the AgroAPI. \code{benchmark_redape}
+and \code{load_redape_pedons} consume the Redape curated GeoTab
+dataset (Vaz et al. 2023, DOI \code{10.48432/PYKKA7}) -- 96 profiles
+hand-reviewed by pedologists, the gold-standard benchmark for the
+Brazilian system.
+
+Three citations have been added everywhere they're discoverable:
+
+\itemize{
+  \item \code{R/classify-smartsolos.R} top-of-file comment block.
+  \item \code{R/classify-smartsolos.R} \code{@references} block on
+        \code{classify_via_smartsolos_api()}.
+  \item \code{inst/CITATION} -- now exposes 4 BibTeX entries:
+        the soilKey package itself + the three Vaz et al. works.
+        \code{citation("soilKey")} renders all four.
+  \item \code{CITATION.cff} -- now lists the three Vaz et al.
+        works under \code{references:} so GitHub's citation parser
+        and Zenodo's metadata indexers pick them up.
+  \item \code{README.md} "Citing" section explicitly documents
+        which Vaz et al. work to cite for which entry point.
+}
+
+The SmartSolos Expert API URL
+(\url{https://www.agroapi.cnptia.embrapa.br/store/apis/info?name=SmartSolosExpert&version=v1&provider=agroapi})
+is now in both \code{classify-smartsolos.R} and the README.
+
+## Removed from README
+
+\itemize{
+  \item Stale version mentions (v0.9.27, v0.9.36, v0.9.40, etc.).
+  \item Portuguese prose ("descobre", "ã"-bearing words in body
+        text, "FEBR" sub-section descriptions in PT).
+  \item "Code-level metrics (v0.9.36)" stats block (let the
+        pkgdown reference site be the canonical source for
+        function counts; in-README counts age fast).
+  \item References to a "Notes for life" footer that doesn't
+        belong in a CRAN-grade README.
+}
+
+## CRAN-readiness
+
+\code{R CMD check --as-cran}: still 0 ERRORs / 0 WARNINGs / 2 trivial
+NOTEs (new submission + HTML tidy local-env). README refresh does
+not affect the check status.
+
+
 # soilKey 0.9.95 (2026-05-09)
 
 The "**post-lazy-fetch sweep + CITATION.cff bump**" release.

diff --git a/R/classify-smartsolos.R b/R/classify-smartsolos.R
@@ -1,19 +1,36 @@
 # =============================================================================
-# v0.9.54 -- SmartSolosExpert REST API client (cross-validation eixo).
+# v0.9.54 -- SmartSolos Expert REST API client (cross-validation axis).
 #
-# Glauber Vaz's PROLOG implementation of the SiBCS classifier is exposed
-# by Embrapa's AgroAPI as a REST endpoint. This module wraps it so soilKey
-# users can cross-validate the local classifier against an authoritative
-# Embrapa-hosted reference.
+# Glauber Vaz's PROLOG implementation of the Brazilian SiBCS classifier
+# is exposed by Embrapa's AgroAPI as a REST endpoint. This module wraps
+# it so soilKey users can cross-validate the local classifier against
+# an authoritative Embrapa-hosted reference.
 #
-# Endpoint (Swagger):
+# API home (registration + Swagger):
+#   https://www.agroapi.cnptia.embrapa.br/store/apis/info?name=SmartSolosExpert&version=v1&provider=agroapi
+#
+# Endpoints:
 #   POST  https://api.cnptia.embrapa.br/smartsolos/expert/v1/classification
 #   POST  https://api.cnptia.embrapa.br/smartsolos/expert/v1/verification
 #
 # Auth:
 #   Authorization: Bearer <token>
 #   Token comes from registration at agroapi.cnptia.embrapa.br
 #   Set via env var AGROAPI_TOKEN (or argument api_key=).
+#
+# Citation (please cite both when using SmartSolos cross-validation):
+#   * Vaz, G. J., Silva Neto, L. de F. da, & Barbedo, J. G. A. (2025).
+#     SmartSolos Expert: an expert system for Brazilian soil classification.
+#     Smart Agricultural Technology, 10, 100735.
+#   * Vaz, G. J., Silva Neto, L. de F. da, Lima, R. N., & Oliveira,
+#     S. R. de M. (2019). Uma API para a classificacao de solos do Brasil.
+#     In: 12. Congresso Brasileiro de Agroinformatica, Indaiatuba.
+#     Anais, p. 63-72. SBIAGRO, Ponta Grossa.
+#
+# Curated profile dataset (used by inst/benchmarks/run_redape.R):
+#   * Vaz, G. J., Silva Jr, A. F., & Silva Neto, L. de F. da (2023).
+#     Brazilian soil data for taxonomic classification. Redape, V1.
+#     DOI: 10.48432/PYKKA7.
 # =============================================================================