GeoNum Engine - Command Reference
=================================
(c) 2026 VaultSync Solutions Inc. All rights reserved.
Patent pending - U.S. Provisional 63/970,430. Proprietary; source not shipped.

GeoNum Engine performs drift-tracked arithmetic. Every result carries an
explicit drift figure and a relative-uncertainty figure derived from the
engine's own propagation - not a claimed digit count. Precision is tracked
through the calculation rather than assumed. An unknown identifier or an
unsupported function yields an explicit unsupported/ERROR status, never a
fabricated number.


SYNOPSIS
--------
  geonum <command> [options]

  geonum compute  --input FILE --output FILE
  geonum compute  --expression "<math>" [--params FILE|JSON] [--precision N] [--zone NAME] [--output FILE]
  geonum compute  --domain NAME --params "[..]" [--zone NAME] [--output FILE]
  geonum validate --domain NAME [--precision N] [--zone NAME] [--output FILE]
  geonum docs
  geonum help [compute|validate]
  geonum support ["message"]
  geonum version


COMMAND: compute
----------------
Evaluate a math expression or a named physics formula and return the value
together with its trust verdict.

Input is selected in this precedence order:

  --input FILE      A JSON document drives the run. Two shapes are accepted:

                    1) A single OBJECT describing one computation:
                         "expression" (or "expr") : string, the math to evaluate
                         "domain"     (or "formula"): string, a named formula
                         "params"     : object {name:number} for an expression,
                                        or array [..] for a domain
                         "zone"       : optional zone name (see ZONES)
                       "expression" takes precedence over "domain" if both exist.

                    2) A top-level ARRAY of those objects = BATCH MODE. Each
                       item is computed in order and the run emits a JSON
                       array of result objects (one per item, same order).
                       Each result object gains an "index" field, and an
                       optional per-item "label" (string) is echoed back if
                       present. Per-item "zone" and "precision" override the
                       CLI --zone/--precision defaults for that item only.
                       An item that names neither expression nor domain
                       returns an explicit "unsupported" result -- no item
                       is silently dropped. Batch exit code: 0 if every
                       item's status is "ok", else 1 (results are emitted
                       either way).

  --expression STR  A math expression. Operators + - * / ^, parentheses, and
                    built-in constants/functions (pi, c, hbar, G, kb, h, me,
                    na, sigma, ...). An optional "label = rhs" form is
                    accepted; only the right-hand side is evaluated and the
                    label is echoed back.

  --domain NAME     A named formula evaluated against IEEE-754 and GeoNum.
                    Recognized: e_mc2, hawking, de_broglie, bohr_energy,
                    stefan_boltzmann, wien, planck_energy, schwarzschild,
                    coulomb. Other names run but are flagged unknown_domain.

Options:

  --params FILE|JSON  Variable bindings. For --expression: a JSON object
                      {"D":1.0,"C":2.99e8}; identifiers are substituted as
                      whole tokens only (DC is one identifier, not D*C, so
                      undeclared names stay undeclared and are reported
                      honestly). For --domain: a JSON array of positional
                      numbers, e.g. "[1.989e30]". The value may be an inline
                      JSON string or a path to a JSON file.

  --precision N       Recorded as the requested precision and echoed in the
                      output as precision_requested. GeoNum precision is
                      drift-tracked; N is NOT a guaranteed digit count.

  --zone NAME         Zone tessellation (see ZONES). Default: lucas.

  --output FILE       Write the JSON result to FILE instead of stdout.
                      A short confirmation is written to stderr.

compute JSON output (expression):
  kind, label, expression, evaluated, zone, precision_requested,
  value, drift, rel_uncertainty_pct, trust, status, engine, note,
  copyright, patent

compute JSON output (domain):
  kind, domain, params, zone, precision_requested, ieee754, value,
  drift, rel_uncertainty_pct, trust, status, engine, copyright, patent

Examples:
  geonum compute --expression "hbar*c^3/(8*pi*G*1.989e30*kb)"
  geonum compute --expression "E = D*C^2" --params domain.json
  geonum compute --input params.json --output results.json
  geonum compute --domain hawking --params "[1.989e30]"

  # batch mode: batch.json is a JSON array of job objects
  #   [ { "label": "E=mc^2", "expression": "E = D*C^2", "params": {"D":1.989e30} },
  #     { "domain": "hawking", "params": [1.989e30] },
  #     { "expression": "hbar*c^3/(8*pi*G*1.989e30*kb)", "zone": "sinh" } ]
  geonum compute --input batch.json --output results.json


COMMAND: validate
-----------------
Run a computation against a built-in reference and report PASS/FAIL with the
trust verdict and the engine's drift.

  --domain NAME     Default: hawking. A built-in MPFR-256 reference exists
                    for: hawking. Other domains return status no_reference
                    (honest by design - no fabricated reference) with a
                    non-zero exit; use `geonum compute --domain NAME` for a
                    drift-tracked result instead.

  --precision N     Recorded as requested precision (see note under compute).
  --zone NAME       Zone tessellation. Default: lucas.
  --output FILE     Write the JSON report to FILE.

validate JSON output (hawking):
  kind, domain, zone, precision_requested, reference_mpfr256,
  geonum{value,error_pct,drift}, ieee754{value,error_pct},
  tolerance_pct, trust, result(PASS|FAIL), engine, copyright, patent

Example:
  geonum validate --domain hawking --precision 60
  geonum validate --domain hawking --output report.json


ZONES
-----
The zone boundary set is the scale tessellation; the core arithmetic is the
same in every zone - only scale resolution changes.

  lucas        Default. Lucas-sequence boundaries, 10^-35 to 10^30.
               Multi-scale physics; validated on Hawking radiation.
  linear_ev    Uniform, atomic/molecular energy scale (~10^-2 to 10^2).
  linear_cfd   Uniform, fluid-dynamics grid scale (~10^-6 to 10^3).
  sinh         Sinh-compressed, dense coverage near zero (~10^-10 to 10^2).


TRUST VERDICTS
--------------
Derived from the engine's own relative drift, not a digit claim:

  PRECISE      relative uncertainty < 0.5 %
  DRIFTING     relative uncertainty < 5 %   (verify before relying on it)
  UNRELIABLE   relative uncertainty >= 5 %  (do not trust without checking)
  ERROR        value/uncertainty non-finite, or input unsupported


EXIT CODES
----------
  0   success
  1   usage error; validate with no built-in reference for the domain;
      batch run where at least one item's status was not "ok"
  2   licensing: trial expired, key rejected, or could not verify in the
      offline grace window
  3   validate ran but the result FAILED its tolerance


LICENSING
---------
On first run the binary self-enforces a 3-day evaluation - no card needed to
evaluate. To license, subscribe at https://geonum.getvaultsync.com/#pricing
and supply the key by either:

  GEONUM_LICENSE_KEY        environment variable (checked first), or
  %USERPROFILE%\.geonum\license   (or ~/.geonum/license)

Trial / grace state lives in %USERPROFILE%\.geonum\state (or ~/.geonum).
The key is verified against GEONUM_LICENSE_URL (default
https://license.getvaultsync.com) and is re-confirmed periodically; a
14-day offline grace window applies if the license server is unreachable.

Tiers (flat monthly, 3-day trial, no discounts, no contracts, cancel
anytime): Individual $60 - Commercial $120 - Infrastructure $240.
Source is not shipped; the compiled binary is the licensed artifact.


GETTING HELP INSIDE THE CLI
---------------------------
  geonum help               overview of all commands
  geonum help compute       detailed compute options
  geonum help validate      detailed validate options
  geonum docs               print this full reference
  geonum version            version, copyright, patent line


SUPPORT
-------
  geonum support "what you need"

Builds a diagnostic report (version, OS/arch, license/trial state, and your
message), opens a pre-addressed email to the maintainer, and always prints
the full report and the address so it works even with no mail client
configured. Direct assistance: support@getvaultsync.com
OEM / sub-licensing: licensing@getvaultsync.com
