docs: "source cell" describes 6% of the corpus — say what we actually keep

CITATION.cff

@@ -5,7 +5,7 @@ title: "GreenCalculus SDKs"
 abstract: >
   Official Python and JavaScript/TypeScript clients for the GreenCalculus carbon
   API, plus a Google Sheets add-in and a Postman collection. Every emission factor
-  returned carries the exact cell it was read from and the data version it was read
+  returned carries the exact place in the source it was read from and the data version it was read
   at, and every calculation returns its full working with a deterministic receipt
   hash, so a published figure can be reproduced and checked rather than trusted.
   The corpus reads without an API key.

CONTRIBUTING.md

@@ -17,7 +17,7 @@ names often differ from what you'd guess.
 [Report a wrong value](https://github.com/greencalculus/greencalculus-sdk/issues/new?template=wrong-value.yml).
 A carbon figure that is quietly wrong is worse than one that is missing. Every
 factor carries a verification link (`citation.proof_url`) showing the publisher,
-the document and the exact cell — if that cell doesn't say what we say it says,
+the document and the exact place within it — if that place doesn't say what we say it says,
 we want to know, and we'd rather hear it in public.
 
 ## Code

README.md

@@ -8,7 +8,7 @@
 [![smithery](https://smithery.ai/badge/greencalculus/api)](https://smithery.ai/servers/greencalculus/api)
 [![Google Workspace Marketplace](https://img.shields.io/badge/Google%20Sheets-add--on-34A853)](https://workspace.google.com/marketplace/app/greencalculus_emission_factors/172913449875)
 
-Official client libraries for the **[GreenCalculus API](https://greencalculus.com/developers?ref=github-sdk)** — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with **the exact cell it came from and the data version it was read at**, so you return citable numbers instead of guesses.
+Official client libraries for the **[GreenCalculus API](https://greencalculus.com/developers?ref=github-sdk)** — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with **the exact place in the source it came from and the data version it was read at**, so you return citable numbers instead of guesses.
 
 Not writing code? The same corpus is a spreadsheet formula: the **[Google Sheets add-on](https://workspace.google.com/marketplace/app/greencalculus_emission_factors/172913449875)** has been listed and Google-verified since 11 September 2026 — see [`sheets/`](./sheets).
 
@@ -68,10 +68,10 @@ print(r["emissions"]["value"], r["source"]["id"])
 
 ## What you get
 
-- **16,000+ sourced factors** across grid, fuels, freight, refrigerants, AFOLU, CBAM, construction and spend-based EEIO. Every value returns its source cell, licence and uncertainty.
+- **16,000+ sourced factors** across grid, fuels, freight, refrigerants, AFOLU, CBAM, construction and spend-based EEIO. Every value returns its source reference, licence and uncertainty.
 - **Seven calculation engines** — GHG Protocol activity, PCAF financed emissions, embodied EN 15978, electricity, freight, spend-based, business travel. The full working, never just a total.
 - **Reproducible** — a deterministic receipt hash on every result, and `as_of=` pins any factor to a past data version so a figure re-runs identically in an audit.
-- **Checkable by the reader** — every factor has a permanent verification page showing the publisher, the document, the exact cell and whether it may be republished.
+- **Checkable by the reader** — every factor has a permanent verification page showing the publisher, the document, the exact place within it and whether it may be republished.
 - **Agent-native** — the same data over MCP at `mcp.greencalculus.com`.
 
 ## Use it from an AI agent (MCP)

js/README.md

@@ -1,6 +1,6 @@
 # greencalculus
 
-The official JavaScript / TypeScript client for the [GreenCalculus API](https://greencalculus.com/developers?ref=npm) — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with the exact cell it came from and the data version it was read at.
+The official JavaScript / TypeScript client for the [GreenCalculus API](https://greencalculus.com/developers?ref=npm) — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with the exact place in the source it came from and the data version it was read at.
 
 Zero dependencies. Uses the platform `fetch` (Node 18+ or any browser). Ships with TypeScript types.
 

js/src/co2js.ts

@@ -3,7 +3,7 @@
  *
  * CO2.js bundles one unversioned average per country (Ember). This helper
  * fetches the same quantity from GreenCalculus — with the publisher, the
- * exact source cell, the data version and a public proof URL — and shapes it
+ * exact source reference, the data version and a public proof URL — and shapes it
  * as the `gridIntensity` option CO2.js already accepts, so a web-carbon
  * estimate can carry an audit trail. No dependency on @tgwf/co2; pass the
  * result into its `perVisitTrace` / `perByteTrace` options yourself.

js/src/index.ts

@@ -2,7 +2,7 @@
  * GreenCalculus — the carbon-accounting API.
  *
  * Sourced greenhouse-gas emission factors and audit-traced calculations, every
- * value traceable to its source cell and data version. Zero dependencies (uses
+ * value traceable to its source reference and data version. Zero dependencies (uses
  * the platform `fetch`; Node 18+ or any browser).
  *
  *   import { GreenCalculus } from "greencalculus";
@@ -146,7 +146,7 @@ export class GreenCalculus {
 
   /**
    * Browse the corpus — keyless, edge-cached. Full rows including the value,
-   * source cell and licence. Params: key_prefix, section, family, search, limit, offset, cursor.
+   * source reference and licence. Params: key_prefix, section, family, search, limit, offset, cursor.
    */
   browse(params: Record<string, unknown> = {}): Promise<Json> {
     return this.request("GET", "/v1/factors", { params });

postman/description.md

@@ -1,6 +1,6 @@
 **Emission factors you can cite, and calculations an auditor can re-run.**
 
-16,000+ greenhouse-gas emission factors from 137 publishers — DEFRA, EPA, Ember, IPCC, ECCC, ÖKOBAUDAT. Every value comes back with the exact spreadsheet cell it was read from:
+16,000+ greenhouse-gas emission factors from 137 publishers — DEFRA, EPA, Ember, IPCC, ECCC, ÖKOBAUDAT. Every value comes back with the exact place in the source it was read from — here, a spreadsheet cell:
 
 ```json
 "value": 0.13096,  "unit": "kg CO2e per kWh",

postman/greencalculus.postman_collection.json

@@ -2,7 +2,7 @@
   "info": {
     "_postman_id": "6230755a-8812-51b9-8803-8b2303d66ea8",
     "name": "GreenCalculus API",
-    "description": "**Emission factors you can cite, and calculations an auditor can re-run.**\n\n16,000+ greenhouse-gas emission factors from 137 publishers — DEFRA, EPA, Ember, IPCC, ECCC, ÖKOBAUDAT. Every value comes back with the exact spreadsheet cell it was read from:\n\n```json\n\"value\": 0.13096,  \"unit\": \"kg CO2e per kWh\",\n\"source\":   { \"cell_ref\": \"'UK electricity'!E25\", \"retrieved\": \"2026-06-18\" },\n\"licence\":  { \"name\": \"Open Government Licence v3.0\", \"redistributable\": true },\n\"citation\": { \"proof_url\": \"https://verify.greencalculus.com/grid.gbr.electricity.location_based@2026.192\" }\n```\n\nThat proof link resolves the value **as it stood at that data version**. So a report re-run in eleven months lands on the same number instead of a quietly-revised one — and the reviewer who asks \"where did 0.13096 come from?\" gets a cell reference, not a shrug. Most carbon APIs hand you a figure and bury its origin.\n\n## Press Send right now\n\n**Ten of these 28 requests need no key and no signup.** Everything in **Discovery** is open: browse the corpus, read the change feed, check country coverage, and see which factors we deliberately *don't* hold and why. Open any of them and send it — nothing to configure.\n\n## For the other eighteen\n\nSet the `api_key` collection variable. Free, no card: **https://greencalculus.com/developers/**\n\nThat unlocks the calculation engines, which return the full working rather than a bare total — GHG Protocol activity, Scope 2 location + market, PCAF financed emissions, EN 15978 embodied carbon, GLEC freight, spend-based EEIO. Each response shows the factor used, its source, and the arithmetic.\n\n## For agents\n\nThe same corpus is an MCP server with twelve tools at `https://mcp.greencalculus.com`, on the official MCP registry as `com.greencalculus/api` — so a model can pull a sourced number mid-conversation instead of inventing one.\n\n---\n\nDocs: https://greencalculus.com/developers/docs/ · OpenAPI: https://api.greencalculus.com/openapi.json · SDKs for [Python and JavaScript](https://github.com/greencalculus/greencalculus-sdk) · [Google Sheets add-on](https://workspace.google.com/marketplace/app/greencalculus_emission_factors/172913449875)",
+    "description": "**Emission factors you can cite, and calculations an auditor can re-run.**\n\n16,000+ greenhouse-gas emission factors from 137 publishers — DEFRA, EPA, Ember, IPCC, ECCC, ÖKOBAUDAT. Every value comes back with the exact place in the source it was read from — here, a spreadsheet cell:\n\n```json\n\"value\": 0.13096,  \"unit\": \"kg CO2e per kWh\",\n\"source\":   { \"cell_ref\": \"'UK electricity'!E25\", \"retrieved\": \"2026-06-18\" },\n\"licence\":  { \"name\": \"Open Government Licence v3.0\", \"redistributable\": true },\n\"citation\": { \"proof_url\": \"https://verify.greencalculus.com/grid.gbr.electricity.location_based@2026.192\" }\n```\n\nThat proof link resolves the value **as it stood at that data version**. So a report re-run in eleven months lands on the same number instead of a quietly-revised one — and the reviewer who asks \"where did 0.13096 come from?\" gets a cell reference, not a shrug. Most carbon APIs hand you a figure and bury its origin.\n\n## Press Send right now\n\n**Ten of these 28 requests need no key and no signup.** Everything in **Discovery** is open: browse the corpus, read the change feed, check country coverage, and see which factors we deliberately *don't* hold and why. Open any of them and send it — nothing to configure.\n\n## For the other eighteen\n\nSet the `api_key` collection variable. Free, no card: **https://greencalculus.com/developers/**\n\nThat unlocks the calculation engines, which return the full working rather than a bare total — GHG Protocol activity, Scope 2 location + market, PCAF financed emissions, EN 15978 embodied carbon, GLEC freight, spend-based EEIO. Each response shows the factor used, its source, and the arithmetic.\n\n## For agents\n\nThe same corpus is an MCP server with twelve tools at `https://mcp.greencalculus.com`, on the official MCP registry as `com.greencalculus/api` — so a model can pull a sourced number mid-conversation instead of inventing one.\n\n---\n\nDocs: https://greencalculus.com/developers/docs/ · OpenAPI: https://api.greencalculus.com/openapi.json · SDKs for [Python and JavaScript](https://github.com/greencalculus/greencalculus-sdk) · [Google Sheets add-on](https://workspace.google.com/marketplace/app/greencalculus_emission_factors/172913449875)",
     "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
   },
   "auth": {

python/README.md

@@ -1,6 +1,6 @@
 # greencalculus
 
-The official Python client for the [GreenCalculus API](https://greencalculus.com/developers?ref=pypi) — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with the exact cell it came from and the data version it was read at, so you hand back citable numbers, not guesses.
+The official Python client for the [GreenCalculus API](https://greencalculus.com/developers?ref=pypi) — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with the exact place in the source it came from and the data version it was read at, so you hand back citable numbers, not guesses.
 
 Zero third-party dependencies (standard library only).
 

python/greencalculus/__init__.py

@@ -1,7 +1,7 @@
 """GreenCalculus — the carbon-accounting API.
 
 Sourced greenhouse-gas emission factors and audit-traced calculations, every
-value traceable to its source cell and data version.
+value traceable to its source reference and data version.
 
     from greencalculus import GreenCalculus
 
@@ -166,7 +166,7 @@ def factor(self, key: str, as_of: Optional[str] = None) -> Dict[str, Any]:
 
     def browse(self, **params: Any) -> Dict[str, Any]:
         """Browse the corpus — keyless, edge-cached. Full rows including the
-        value, source cell and licence.
+        value, source reference and licence.
 
         Params: ``key_prefix``, ``section``, ``family``, ``search``, ``limit``,
         ``offset``, ``cursor``.

sheets/README.md

@@ -1,6 +1,6 @@
 # GreenCalculus for Google Sheets
 
-`=GC_FACTOR("grid.gbr.electricity.location_based")` → a sourced emission factor in a cell, with the publisher's exact source cell, the data version and a citation one column over. The spreadsheet is where carbon accounting actually happens; this puts cited factors inside it.
+`=GC_FACTOR("grid.gbr.electricity.location_based")` → a sourced emission factor in a cell, with the publisher's exact source reference, the data version and a citation one column over. The spreadsheet is where carbon accounting actually happens; this puts cited factors inside it.
 
 Keyless by default — the GreenCalculus corpus is open to read. An API key (free) adds `as_of` version pinning.
 
@@ -21,7 +21,7 @@ Find keys at [greencalculus.com/factors](https://greencalculus.com/factors/) or
 
 ## First run
 
-Installing from the Marketplace opens the sidebar (`onInstall` runs in `AuthMode.FULL`, so it may). Until this user has tried it once, the sidebar leads with a one-line "why" (source cell, data version, citation, stays current) and one button, **Build me a starter sheet**: at the selected cell it writes a header row and two rows — UK grid electricity for 1,000 kWh and UK diesel for 500 litres — each with `=GC_EMISSIONS(key, amount)` and a linked short citation `=HYPERLINK(GC_FACTOR(key,"proof"), GC_CITE(key,"short"))`. Cited numbers in one click, no key needed. **Skip** hides the panel. The same block is under *Extensions → GreenCalculus → Build me a starter sheet*. Seen-state is per user (`GC_WELCOMED` in user properties), not per workbook.
+Installing from the Marketplace opens the sidebar (`onInstall` runs in `AuthMode.FULL`, so it may). Until this user has tried it once, the sidebar leads with a one-line "why" (source reference, data version, citation, stays current) and one button, **Build me a starter sheet**: at the selected cell it writes a header row and two rows — UK grid electricity for 1,000 kWh and UK diesel for 500 litres — each with `=GC_EMISSIONS(key, amount)` and a linked short citation `=HYPERLINK(GC_FACTOR(key,"proof"), GC_CITE(key,"short"))`. Cited numbers in one click, no key needed. **Skip** hides the panel. The same block is under *Extensions → GreenCalculus → Build me a starter sheet*. Seen-state is per user (`GC_WELCOMED` in user properties), not per workbook.
 
 ## Sidebar (Extensions → GreenCalculus → Open GreenCalculus)
 

sheets/Sidebar.html

@@ -48,7 +48,7 @@
 
 <section id="welcome" hidden>
   <h3>Emission factors, with their source, in your cells</h3>
-  <p style="margin:6px 0 8px">Every value comes with the publisher's exact source cell, the data version and a citation — and stays current when the publisher updates. That is what an auditor asks for and what a copied number can't give you.</p>
+  <p style="margin:6px 0 8px">Every value comes with the publisher's exact source reference, the data version and a citation — and stays current when the publisher updates. That is what an auditor asks for and what a copied number can't give you.</p>
   <ol>
     <li>Click an empty cell.</li>
     <li>Press <b>Build me a starter sheet</b>: UK electricity and diesel, with emissions and clickable citations.</li>

sheets/package.json

@@ -2,7 +2,7 @@
   "name": "greencalculus-sheets",
   "private": true,
   "version": "0.3.0",
-  "description": "GreenCalculus for Google Sheets — =GC_FACTOR() and friends: sourced emission factors, with the source cell and a citation, in a spreadsheet cell.",
+  "description": "GreenCalculus for Google Sheets — =GC_FACTOR() and friends: sourced emission factors, with the source reference and a citation, in a spreadsheet cell.",
   "scripts": {
     "test": "node --test test/core.test.mjs",
     "push": "clasp push",

sheets/src/Code.js

@@ -278,7 +278,7 @@ function gcHelp() {
     + '<b>=GC_FACTOR(key, [field], [as_of])</b><br>Fields: ' + Object.keys(GC_FIELDS).join(', ') + '<br><br>'
     + '<b>=GC_FACTOR_ROW(key)</b> · <b>=GC_CITE(key, ["short"])</b> · <b>=GC_EMISSIONS(key, qty)</b> · <b>=GC_SEARCH(text)</b> · <b>=GC_VERSION()</b><br>'
     + 'Linked citation: <code>=HYPERLINK(GC_FACTOR(key,"proof"), GC_CITE(key,"short"))</code><br><br>'
-    + 'Every value comes with the publisher\'s exact source cell, the data version and a citation, and stays current when the publisher updates.<br><br>'
+    + 'Every value comes with the publisher\'s exact source reference, the data version and a citation, and stays current when the publisher updates.<br><br>'
     + 'Keys: <a href="' + GC_FACTORS_URL + '" target="_blank">greencalculus.com/factors</a> · '
     + 'Docs: <a href="' + GC_DOCS_URL + '" target="_blank">developers/docs</a> · '
     + '<a href="' + GC_SIGNUP_URL + '" target="_blank">Get a free API key</a> (version pinning)<br><br>'
@@ -436,7 +436,7 @@ function GC_FACTOR(key, field, as_of) {
 }
 
 /**
- * One factor as a row: value, unit, source id, source cell, data version, citation.
+ * One factor as a row: value, unit, source id, source reference, data version, citation.
  *
  * @param {string} key Factor key.
  * @param {boolean} [headers] TRUE to include a header row above the values.
@@ -456,9 +456,9 @@ function GC_FACTOR_ROW(key, headers) {
 }
 
 /**
- * A ready-to-paste citation for a factor: factor name, publisher, source cell,
+ * A ready-to-paste citation for a factor: factor name, publisher, source reference,
  * retrieval date, data version and a public proof link. Pass "short" for a
- * cell-sized form (source id, source cell, data version); wrap in HYPERLINK
+ * cell-sized form (source id, source reference, data version); wrap in HYPERLINK
  * with GC_FACTOR(key,"proof") to make it a link.
  *
  * @param {string|Array<Array<string>>} key Factor key or a range of keys.

sheets/src/core.js

@@ -70,15 +70,15 @@ var GC_FIELDS = {
   name: 'human-readable factor name',
   source: 'source id, e.g. DEFRA_2026',
   publisher: 'publishing organisation',
-  cell: 'exact source cell reference in the publisher’s workbook',
+  cell: 'where in the publisher’s own document the value was read — a workbook cell, a table row or an annex clause',
   retrieved: 'date the row was retrieved from the publisher',
   licence: 'licence name of the source',
   version: 'GreenCalculus data version that served the value',
   gwp: 'GWP set, e.g. AR5_100',
   basis: 'boundary / basis statement for the value',
   scope: 'GHG Protocol scope the factor belongs to',
   citation: 'a ready-to-paste citation line',
-  citation_short: 'a short citation for a cell: source id, source cell, data version',
+  citation_short: 'a short citation for a cell: source id, source reference, data version',
   proof: 'public proof URL pinned to the data version',
 };
 
@@ -280,7 +280,7 @@ function gcCitation(rec) {
 }
 
 /**
- * The short citation for a cell: source id, source cell, data version —
+ * The short citation for a cell: source id, source reference, data version —
  * `DEFRA_2026, 'UK electricity'!E25, v2026.186`. Composed from the fields the
  * API's citation object carries, so it cannot drift from the full line.
  */