gea-program 0.75.0__tar.gz → 0.76.0__tar.gz

{gea_program-0.75.0/gea_program.egg-info → gea_program-0.76.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.75.0
+Version: 0.76.0
 Summary: GEA-Program: downhole gauge monitoring - canonical measurement records, quality rules, drift evaluation with a re-fit change log, well-test validation, alarm management, model cards, store-and-forward, monthly SLA measurement, FAT/SAT protocols and a dashboard, generated from live objects in the client's reporting outline.
 Author: Daniel T. Murphy
 License: MPL-2.0
@@ -463,6 +463,26 @@ keeps them byte for byte and makes the array and electrode stations of
 them. `gea help recorder`; the box's README has the parts, the wiring and
 the clock.
 
+### The tutorial
+
+Every step of GEA and the programs around it, as 27 lessons on the
+**Tutorial** tab (since 0.76.0; `gea help tutorial`): the office's lessons
+first - install, sign in, set up the site, bring wells and data in, the
+well page, the declarations sheet, the patch panel, alarms and
+notifications, the control room, the daily summary and the month-end
+packet, the map and the 3D view, the drilling and production pages,
+seismic, the recorder from the office, reports, the signed dossier and the
+Reader, users and HTTPS, backups and the gate, new versions from inside
+the program, GEA-VPN - and the pad attendant's after: the box and its
+parts, installing the recorder on the Pi, the monitor, the USB mirror and
+joining the VPN. Each lesson names who it is for, the page it is done on
+(a button opens it), how long it takes, the numbered steps with the
+buttons as the page names them, and how you know it worked; each account
+ticks lessons off. **Print the handout** gives the whole course as one
+page for the people who do not sit at the screen. From a terminal:
+`gea tutorial`, `gea tutorial --lesson 3`, `gea tutorial --handout
+--workspace C:\site`.
+
 ### GEA-VPN: the programs on separate computers, one private network
 
 The control panel, each pad's recorder, the operator's window and the
@@ -780,7 +800,7 @@ unsigned, the key hand-overs - and shows the reports as they were signed. A
 reader made from the workspace knows the site's key fingerprints, so it
 says whether a dossier is the site's; it allows no network request, and it
 leaves the trusted time-stamp to `verify_dossier.py`. For a client who wants
-it installed, every release also carries `GEA-Reader-Setup-0.75.0.exe`: GEA
+it installed, every release also carries `GEA-Reader-Setup-0.76.0.exe`: GEA
 Reader as a Windows program of its own - its own icon and taskbar button,
 Check with GEA Reader on a dossier's right-click menu, fingerprints the client
 saves kept on that computer, nothing of GEA-Program. `gea help reader`.
@@ -1545,7 +1565,7 @@ attaches the zips to the GitHub release of that tag.
 
 ### The Windows installer
 
-Every release also carries `GEA-Program-Setup-0.75.0.exe` (for 0.75.0): the
+Every release also carries `GEA-Program-Setup-0.76.0.exe` (for 0.76.0): the
 same Windows kit installed like any Windows program, for the signed-in user
 alone and with no administrator rights (`%LOCALAPPDATA%\Programs\GEA-Program`).
 It asks for the site workspace (an existing one such as `C:\site` is used as
@@ -1564,7 +1584,7 @@ it, removes the program and leaves the workspace. Silent, for a site's
 software deployment:
 
 ```
-GEA-Program-Setup-0.75.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
+GEA-Program-Setup-0.76.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
 ```
 
 The setup is built by Inno Setup 6 from `tools/installer.iss` in the same

{gea_program-0.75.0 → gea_program-0.76.0}/README.md

@@ -424,6 +424,26 @@ keeps them byte for byte and makes the array and electrode stations of
 them. `gea help recorder`; the box's README has the parts, the wiring and
 the clock.
 
+### The tutorial
+
+Every step of GEA and the programs around it, as 27 lessons on the
+**Tutorial** tab (since 0.76.0; `gea help tutorial`): the office's lessons
+first - install, sign in, set up the site, bring wells and data in, the
+well page, the declarations sheet, the patch panel, alarms and
+notifications, the control room, the daily summary and the month-end
+packet, the map and the 3D view, the drilling and production pages,
+seismic, the recorder from the office, reports, the signed dossier and the
+Reader, users and HTTPS, backups and the gate, new versions from inside
+the program, GEA-VPN - and the pad attendant's after: the box and its
+parts, installing the recorder on the Pi, the monitor, the USB mirror and
+joining the VPN. Each lesson names who it is for, the page it is done on
+(a button opens it), how long it takes, the numbered steps with the
+buttons as the page names them, and how you know it worked; each account
+ticks lessons off. **Print the handout** gives the whole course as one
+page for the people who do not sit at the screen. From a terminal:
+`gea tutorial`, `gea tutorial --lesson 3`, `gea tutorial --handout
+--workspace C:\site`.
+
 ### GEA-VPN: the programs on separate computers, one private network
 
 The control panel, each pad's recorder, the operator's window and the
@@ -741,7 +761,7 @@ unsigned, the key hand-overs - and shows the reports as they were signed. A
 reader made from the workspace knows the site's key fingerprints, so it
 says whether a dossier is the site's; it allows no network request, and it
 leaves the trusted time-stamp to `verify_dossier.py`. For a client who wants
-it installed, every release also carries `GEA-Reader-Setup-0.75.0.exe`: GEA
+it installed, every release also carries `GEA-Reader-Setup-0.76.0.exe`: GEA
 Reader as a Windows program of its own - its own icon and taskbar button,
 Check with GEA Reader on a dossier's right-click menu, fingerprints the client
 saves kept on that computer, nothing of GEA-Program. `gea help reader`.
@@ -1506,7 +1526,7 @@ attaches the zips to the GitHub release of that tag.
 
 ### The Windows installer
 
-Every release also carries `GEA-Program-Setup-0.75.0.exe` (for 0.75.0): the
+Every release also carries `GEA-Program-Setup-0.76.0.exe` (for 0.76.0): the
 same Windows kit installed like any Windows program, for the signed-in user
 alone and with no administrator rights (`%LOCALAPPDATA%\Programs\GEA-Program`).
 It asks for the site workspace (an existing one such as `C:\site` is used as
@@ -1525,7 +1545,7 @@ it, removes the program and leaves the workspace. Silent, for a site's
 software deployment:
 
 ```
-GEA-Program-Setup-0.75.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
+GEA-Program-Setup-0.76.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
 ```
 
 The setup is built by Inno Setup 6 from `tools/installer.iss` in the same

{gea_program-0.75.0 → gea_program-0.76.0}/gea/__init__.py

@@ -123,7 +123,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.75.0"
+__version__ = "0.76.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.75.0 → gea_program-0.76.0}/gea/__main__.py

@@ -1023,6 +1023,15 @@ def main(argv=None) -> int:
     p_up.add_argument("--install", type=str, default=None, help="run the fetched GEA-Program-Setup of this version (Windows): the control panel stops and comes back")
     p_up.add_argument("--actor", type=str, default="cli")
 
+    p_tu = sub.add_parser("tutorial", help="the tutorial: every step of GEA and the programs around it as lessons - list them, print one, write the handout (the Tutorial tab does the same by clicking)")
+    p_tu.add_argument("--lesson", type=str, default=None, help="print one lesson by its number (3) or its name (install)")
+    p_tu.add_argument("--handout", action="store_true", help="write the whole course as one printable HTML page (and Markdown)")
+    p_tu.add_argument("--workspace", type=str, default=None, help="with --handout: the workspace whose exports\\tutorial folder gets it (C:\\site); with a workspace, --user shows that person's progress")
+    p_tu.add_argument("--out", type=str, default=None, help="with --handout and no workspace: the HTML file to write (C:\\site\\GEA-Tutorial.html)")
+    p_tu.add_argument("--user", type=str, default="", help="whose progress to show")
+    p_tu.add_argument("--actor", type=str, default="cli")
+    p_tu.add_argument("--json", action="store_true")
+
     p_vp = sub.add_parser("vpn", help="GEA-VPN: the private WireGuard network the programs talk over - make it, add and remove members, write the hub installer and every member's configuration (the Administration card does the same by clicking)")
     p_vp.add_argument("--workspace", type=str, default=None, help="the workspace (C:\\site); keys in keys\\vpn\\network.json, files under exports\\vpn")
     p_vp.add_argument("--create", type=str, default=None, metavar="HOST", help="make the network with the hub at this public name or address (vpn.pad3site.com or 203.0.113.10); the office member is made with it")
@@ -2371,6 +2380,34 @@ def main(argv=None) -> int:
             return 0
         from .doctor import update as _update
         return _update(check_only=a.check, extras=a.extras, as_json=a.json)
+    elif a.cmd == "tutorial":
+        import json as _json
+        from . import tutorial as TU
+        ws = None
+        if a.workspace or os.environ.get("GEA_WORKSPACE"):
+            from .workspace import Workspace
+            ws = Workspace(a.workspace or os.environ.get("GEA_WORKSPACE"))
+        if a.handout:
+            if ws is not None:
+                r = TU.write_handout(ws, a.actor, __version__)
+                print(f"written: {r['html']} and {r['md']} ({r['lessons']} lessons); open the HTML and print it for the PDF")
+                return 0
+            out = a.out or f"GEA-Tutorial-{__version__}.html"
+            with open(out, "w", encoding="utf-8") as f:
+                f.write(TU.handout_html(__version__))
+            print(f"written: {out} ({len(TU.lessons())} lessons); open it and print it for the PDF")
+            return 0
+        if a.lesson:
+            les = TU.lesson(a.lesson)
+            if les is None:
+                raise SystemExit(f"tutorial: no lesson {a.lesson}; `gea tutorial` lists them")
+            print(_json.dumps({k: v for k, v in les.items() if k not in ("path", "html")}, indent=1) if a.json else les["markdown"])
+            return 0
+        if a.json:
+            print(_json.dumps(TU.overview(ws, a.user), indent=1))
+        else:
+            print(TU.text(ws, a.user))
+        return 0
     elif a.cmd == "vpn":
         import json as _json
         from . import vpn as VP

{gea_program-0.75.0 → gea_program-0.76.0}/gea/acceptance_tests.py

@@ -16101,7 +16101,7 @@ def section_dt_vpn(tmp: str) -> None:
     b_pub = "de9edb7d7b7dc1b4d35b61c2ece435373f8343c85b78674dadfc7e146f882b4f"
     shared = "4a5d9d5ba4ce2de1728e3bf480350f25e07e21c947d19e3376f09b3c1e161742"
     pub_a = X.public_key(a_priv); pub_b = X.public_key(b_priv)
-    wg = shutil.which("wg")
+    wg = shutil.which("wg") if os.name != "nt" else None
     wg_same = None
     if wg:
         try:
@@ -16179,14 +16179,20 @@ def section_dt_vpn(tmp: str) -> None:
         box_names = sorted(n.split("/", 1)[1] for n in z.namelist()); box_conf_z = z.read(f"gea-vpn-{box['id']}/gea-vpn.conf").decode(); vpn_sh = z.read(f"gea-vpn-{box['id']}/vpn.sh").decode()
     with zipfile.ZipFile(rd_zip) as z:
         rd_names = sorted(n.split("/", 1)[1] for n in z.namelist())
-    sh = shutil.which("sh")
+    sh = shutil.which("sh") if os.name != "nt" else None          # the scripts run on Linux hosts; Git's sh.exe on a Windows machine is not that
     sh_ok = None
     if sh:
-        sh_ok = all(subprocess.run([sh, "-n", str(root / f)], capture_output=True, timeout=10).returncode == 0 for f in ("hub/install-hub.sh", f"{box['id']}/vpn.sh"))
-    wgq = shutil.which("wg-quick")
+        try:
+            sh_ok = all(any(subprocess.run([sh, "-n", str(root / f)], capture_output=True, timeout=20).returncode == 0 for _ in range(2)) for f in ("hub/install-hub.sh", f"{box['id']}/vpn.sh"))
+        except (OSError, subprocess.SubprocessError):
+            sh_ok = None
+    wgq = shutil.which("wg-quick") if os.name != "nt" else None
     strip_ok = None
     if wgq:
-        strip_ok = all(subprocess.run([wgq, "strip", str(root / f)], capture_output=True, timeout=10).returncode == 0 for f in ("hub/gea-vpn.conf", f"{box['id']}/gea-vpn.conf", "office/gea-vpn.conf"))
+        try:
+            strip_ok = all(any(subprocess.run([wgq, "strip", str(root / f)], capture_output=True, timeout=20).returncode == 0 for _ in range(2)) for f in ("hub/gea-vpn.conf", f"{box['id']}/gea-vpn.conf", "office/gea-vpn.conf"))
+        except (OSError, subprocess.SubprocessError):
+            strip_ok = None
     removed = VP.remove_member(ws, "tester", rd["id"])
     rd_gone_at_once = not rd_zip.exists() and not (root / rd["id"]).exists()
     VP.write_bundles(ws, "tester")
@@ -16278,6 +16284,131 @@ def section_dt_vpn(tmp: str) -> None:
        "and the help page carry it" + (f" [failed: {', '.join(failed4)}]" if failed4 else ""))
 
 
+def section_du_tutorial(tmp: str) -> None:
+    """Section DU - the tutorial: every lesson held to its contract (the header, who and where, numbered steps, the
+    "you know it worked when" section, help pages that exist, a page that exists in the control panel, no
+    placeholder); every page the lessons name is a page of the control panel and every button a lesson names in
+    bold is on that page or in a help page; progress kept per account; the handout written whole; the routes, the
+    tab, the command and the help page."""
+    import http.cookiejar
+    import urllib.error
+    import urllib.request
+    from . import __version__
+    from . import helplib as H
+    from . import tutorial as TU
+    from .service import Service, Users
+    from .workspace import Workspace
+    pkg = Path(__file__).parent
+    d = Path(tmp, "du"); d.mkdir()
+    app_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    main_src = (pkg / "__main__.py").read_text(encoding="utf-8")
+    help_all = "\n".join((pkg / "help" / f).read_text(encoding="utf-8") for f in os.listdir(pkg / "help") if f.endswith(".md"))
+    # -- DU1 the lessons against the contract ------------------------------------------------------------------------------
+    ls = TU.lessons()
+    nav = re.search(r"const NAV = \[(.*?)\];", app_src)
+    views = set(re.findall(r"'(#/[a-z0-9]*)'", nav.group(1))) if nav else set()
+    bad_contract = {l["id"]: TU.check(l["id"]) for l in ls if TU.check(l["id"])}
+    bad_where = [l["id"] for l in ls if l["where"] not in views]
+    numbers = [l["n"] for l in ls]
+    # every **Button** a lesson names must be on the page or in a help page (the lessons describe what is there)
+    unknown_buttons = []
+    for l in ls:
+        body = TU.lesson(l["id"])["body"]
+        for b in re.findall(r"\*\*([^*]+)\*\*", body):
+            b_ = b.rstrip(".:")
+            if len(b_) > 48 or b_[0].islower() or b_ in ("You know it worked when",):
+                continue
+            key = b_.replace("...", "").strip()
+            if key and key not in app_src and key not in help_all and key not in body.replace("**", "").replace(key, "", 1):
+                unknown_buttons.append(f"{l['n']}: {b_}")
+    parts_cover = all(any(a <= n <= b for name, (a, b) in TU.PARTS) for n in numbers)
+    c1 = {
+        "count": len(ls) >= 27 and numbers == list(range(1, len(ls) + 1)),
+        "contract": not bad_contract,
+        "pages_exist": not bad_where,
+        "both_audiences": {l["who"] for l in ls} == {"office", "pad"} and sum(1 for l in ls if l["who"] == "pad") >= 3,
+        "parts": parts_cover and len(TU.PARTS) == 8,
+        "buttons_known": not unknown_buttons,
+        "every_program": all(any(w in (l["title"] + " " + l["summary"]).lower() for l in ls) for w in ("install", "reader", "recorder", "vpn", "dossier", "patch", "backup")),
+    }
+    failed1 = [k for k, v in c1.items() if not v]
+    ok(not failed1,
+       f"DU1 the {len(ls)} lessons are numbered without a gap, each with who it is for, the page it is done on (a page of the control panel), how long, "
+       "a summary, three or more numbered steps, the \"you know it worked when\" section and help pages that exist; every button named in bold is on "
+       "the page or in a help page; both audiences, eight parts; install, the reader, the recorder, the VPN, the dossier, the patches and the backup "
+       "each have a lesson" + (f" [failed: {', '.join(failed1)}" + (f"; {list(bad_contract.items())[:2]}" if bad_contract else "") + (f"; where {bad_where}" if bad_where else "")
+                              + (f"; buttons {unknown_buttons[:4]}" if unknown_buttons else "") + "]" if failed1 else ""))
+    # -- DU2 progress, the handout, the routes, the tab, the command, the help ----------------------------------------------
+    ws = Workspace.create(str(d / "ws"), "Pad 3 tutorial", actor="tester")
+    m1 = TU.mark(ws, "op", "install")
+    m2 = TU.mark(ws, "op", "3")
+    m3 = TU.mark(ws, "viewer", "install")
+    ov = TU.overview(ws, "op")
+    TU.mark(ws, "op", "install", done=False)
+    ov2 = TU.overview(ws, "op")
+    try:
+        TU.mark(ws, "op", "nothing-of-the-kind"); mark_bad = False
+    except KeyError:
+        mark_bad = True
+    hand = TU.write_handout(ws, "tester", __version__)
+    hh = Path(hand["html"]).read_text(encoding="utf-8")
+    hm = Path(hand["md"]).read_text(encoding="utf-8")
+    Users(str(Path(ws.path, "users.json"))).add("op", "op-pass-123", "operator")
+    Users(str(Path(ws.path, "users.json"))).add("vw", "vw-pass-123", "viewer")
+    svc = Service(ws.path, port=0, scheduler=False).start()
+    base = svc.url.rstrip("/")
+
+    def opener_():
+        return urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
+
+    def call(op, method, path, body=None, raw_=False):
+        rq = urllib.request.Request(base + path, method=method, data=(json.dumps(body).encode() if body is not None else None))
+        rq.add_header("Content-Type", "application/json"); rq.add_header("X-GEA-Action", "1")
+        try:
+            with op.open(rq, timeout=60) as rr_:
+                data = rr_.read()
+                return rr_.status, (data if raw_ else json.loads(data)), rr_.headers
+        except urllib.error.HTTPError as e:
+            return e.code, (e.read() if raw_ else json.loads(e.read() or b"{}")), e.headers
+    try:
+        anon = opener_()
+        s_anon, _, _ = call(anon, "GET", "/api/tutorial")
+        vw = opener_(); call(vw, "POST", "/api/login", {"name": "vw", "password": "vw-pass-123"})
+        s_v, ov_v, _ = call(vw, "GET", "/api/tutorial")
+        s_vl, les_v, _ = call(vw, "GET", "/api/tutorial/install")
+        s_vd, _, _ = call(vw, "POST", "/api/tutorial/done", {"lesson": "install"})
+        s_v2, ov_v2, _ = call(vw, "GET", "/api/tutorial")
+        s_vh, _, _ = call(vw, "POST", "/api/tutorial/handout", {})
+        s_vp, page_, ph = call(vw, "GET", "/api/tutorial/handout.html", raw_=True)
+        s_404, _, _ = call(vw, "GET", "/api/tutorial/no-such-lesson")
+        op_ = opener_(); call(op_, "POST", "/api/login", {"name": "op", "password": "op-pass-123"})
+        s_oh, oh, _ = call(op_, "POST", "/api/tutorial/handout", {})
+        s_ol, les_o, _ = call(op_, "GET", "/api/tutorial/3")
+    finally:
+        svc.stop()
+    acts = {a["action"] for a in ws.audit_log()}
+    c2 = {
+        "progress": "install" in m1 and "site" in m2 and ov["n_done"] == 2 and ov["next"] == "sign-in" and ov2["n_done"] == 1 and "install" not in TU.progress(ws, "op")
+                    and "install" in TU.progress(ws, "viewer") and mark_bad,
+        "handout": hand["lessons"] == len(ls) and all(f'id="l{l["n"]}"' in hh for l in ls) and "<!doctype html>" in hh and hm.count("\n# ") >= len(ls) and "Contents" in hh and "You know it worked when" in hh,
+        "routes": s_anon in (401, 403) and s_v == 200 and ov_v["n_lessons"] == len(ls) and s_vl == 200 and les_v["id"] == "install" and les_v["next"] == "sign-in" and les_v["prev"] is None
+                  and "<ol>" in les_v["html"] and s_vd == 200 and ov_v2["n_done"] == 1 and s_vh == 403 and s_oh == 200 and Path(oh["html"]).is_file() and s_404 == 404
+                  and s_ol == 200 and les_o["n"] == 3 and les_o["prev"] == "sign-in",
+        "print": s_vp == 200 and b"<!doctype html>" in page_ and "inline" in str(ph.get("Content-Disposition", "")) and f"GEA-Tutorial-{__version__}" in str(ph.get("Content-Disposition", "")),
+        "audit": {"tutorial.handout", "tutorial.print"} <= acts,
+        "tab": "['#/tutorial', 'Tutorial']" in app_src and "VIEWS.tutorial" in app_src and all(t_ in app_src for t_ in ("/api/tutorial/done", "/api/tutorial/handout", "Open the page this lesson is about", "Mark this lesson done", "Print the handout")),
+        "cli": 'add_parser("tutorial"' in main_src and '"--lesson"' in main_src and '"--handout"' in main_src and "TU.write_handout" in main_src,
+        "help": not H.check("tutorial") and any(t_ == "tutorial" for t_, _, _ in H.INDEX) and H.VIEW_TOPIC.get("tutorial") == "tutorial",
+        "ol_render": "<ol>" in H.to_html("1. one\n2. two\n") and "</ol>" in H.to_html("1. one\n2. two\n") and "<ul>" in H.to_html("- a\n- b\n"),
+    }
+    failed2 = [k for k, v in c2.items() if not v]
+    ok(not failed2,
+       "DU2 progress is kept per account (a lesson marked done, by number or by name, and undone; an unknown lesson refused); the handout is written "
+       "whole as HTML and Markdown with every lesson; the routes (anonymous refused; a viewer reads, ticks and prints; writing the handout into the "
+       "workspace takes the operator role; an unknown lesson 404); the audit lines; the Tutorial tab, the tutorial command and the help page carry "
+       "it; numbered steps render as a list" + (f" [failed: {', '.join(failed2)}]" if failed2 else ""))
+
+
 def main() -> int:
     print("GEA-Program - ACCEPTANCE SUITE (the product gate)")
     # a handle a job subprocess still holds at the end must not turn a finished gate into a traceback on Windows:
@@ -16405,6 +16536,7 @@ def main() -> int:
         section_dr_field_recorder(tmp)
         section_ds_updates(tmp)
         section_dt_vpn(tmp)
+        section_du_tutorial(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

{gea_program-0.75.0 → gea_program-0.76.0}/gea/help/IT_SECURITY.md

@@ -167,6 +167,11 @@ declared extras.
   addresses; the programs' own sign-in, roles and hashes apply through it
   unchanged, and the box's page is still bound to the pad network and the
   tunnel address only.
+- **The tutorial** (since 0.76.0): the lessons are files inside the
+  program; reading one writes nothing. A person's ticks are kept in the
+  workspace (`records\tutorial_progress.json`, by account name, no more);
+  the handout is written only on request into `exports\tutorial\` and
+  carries nothing of the site but its name. Both are audit lines.
 
 ## What it records
 

{gea_program-0.75.0 → gea_program-0.76.0}/gea/help/install.md

@@ -2,7 +2,7 @@
 
 > GEA-Program-Setup: the program installed for you like any Windows program - a window of its own, an icon in the notification area, Start-menu and desktop shortcuts, an Add/Remove Programs entry, upgrades in place - with no administrator rights and the site's data left where it is.
 
-**The command**: download the setup from the release on GitHub (`GEA-Program-Setup-0.75.0.exe` for this version) and run it. It installs for you alone, under `%LOCALAPPDATA%\Programs\GEA-Program`, and asks for the site workspace - the folder that holds the wells, reports, records, accounts and keys. An existing one such as `C:\site` is used exactly as it is, its name included; for a new one (by default `%LOCALAPPDATA%\GEA-Program\site`) it also asks the site's name, which heads every report, and makes the workspace with it (left empty, the workspace is named after its folder; an administrator renames the site in Administration's site settings). Then the Start menu's **GEA-Program** (and the desktop shortcut) starts the control panel when it is not running and opens it in a window of its own. A newer setup installs over the older one: it stops the control panel, replaces the program, keeps the workspace and the choices made before. For a site's software deployment: `GEA-Program-Setup-0.75.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"` (`/SITENAME` names a workspace the setup makes; one that exists keeps its own name). From a terminal: `gea launch` does what the shortcut does, `gea launch --selftest` says what it would do, `gea tray --selftest` checks the icon.
+**The command**: download the setup from the release on GitHub (`GEA-Program-Setup-0.76.0.exe` for this version) and run it. It installs for you alone, under `%LOCALAPPDATA%\Programs\GEA-Program`, and asks for the site workspace - the folder that holds the wells, reports, records, accounts and keys. An existing one such as `C:\site` is used exactly as it is, its name included; for a new one (by default `%LOCALAPPDATA%\GEA-Program\site`) it also asks the site's name, which heads every report, and makes the workspace with it (left empty, the workspace is named after its folder; an administrator renames the site in Administration's site settings). Then the Start menu's **GEA-Program** (and the desktop shortcut) starts the control panel when it is not running and opens it in a window of its own. A newer setup installs over the older one: it stops the control panel, replaces the program, keeps the workspace and the choices made before. For a site's software deployment: `GEA-Program-Setup-0.76.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"` (`/SITENAME` names a workspace the setup makes; one that exists keeps its own name). From a terminal: `gea launch` does what the shortcut does, `gea launch --selftest` says what it would do, `gea tray --selftest` checks the icon.
 
 **The window**: Microsoft Edge's app window (`msedge --app=`: the control panel with no tabs and no address bar, its own button on the taskbar, which shows the program's derrick and pins as GEA-Program, not as Edge), with a browser profile of its own (`%LOCALAPPDATA%\GEA-Program\window`, no extensions; the first time, Edge may say it signed that profile in to your Microsoft account - Got it), else Google Chrome's, else a tab in the default browser. Where the browser keeps no cookies (its settings or a policy block them), the sign-in page says so and the control panel holds the sign-in itself, in the window's address, until the window is closed. The control panel itself runs with no window of its own: `gea supervise` keeps it running in the background, starts it again when it asks for a restart, and writes everything it would have shown in a console - the start, the sign-ins, the jobs, a stop and why - to `records\console.log` in the workspace. No PowerShell or console window opens. The kit's `start-dashboard.cmd` still runs it in a console window, for a site that wants to watch it there.
 
@@ -18,7 +18,7 @@
 
 **The number to check**: Add/Remove Programs lists GEA-Program with the version you installed; `gea doctor --workspace C:\site` ends with `nothing blocks serving`; the Start menu's **Verify GEA-Program** runs the acceptance gate from the installation and ends with `[ACCEPTANCE] OK - N checks passed`. The release's build installs, upgrades and uninstalls the setup silently before it is published, with the control panel running, and checks the workspace untouched afterwards.
 
-**Signed**: when the publisher's code-signing certificate is configured for the build, the setup is signed with it (Authenticode, timestamped) and Windows names the publisher; until then it ships unsigned and Windows SmartScreen says "unknown publisher" (More info, then Run anyway). The build's provenance holds either way: `gh attestation verify GEA-Program-Setup-0.75.0.exe -R Daniel8Murphy0007/GEA-Program`. The uninstaller the setup leaves behind is Inno Setup's own and is not signed separately.
+**Signed**: when the publisher's code-signing certificate is configured for the build, the setup is signed with it (Authenticode, timestamped) and Windows names the publisher; until then it ships unsigned and Windows SmartScreen says "unknown publisher" (More info, then Run anyway). The build's provenance holds either way: `gh attestation verify GEA-Program-Setup-0.76.0.exe -R Daniel8Murphy0007/GEA-Program`. The uninstaller the setup leaves behind is Inno Setup's own and is not signed separately.
 
 **What this page will not call a measurement**: the icon's running or stopped is whether the control panel's port answers on this computer, read every three seconds - not whether every patch, job or report behind it is healthy (Home and the Verification page say that).
 

{gea_program-0.75.0 → gea_program-0.76.0}/gea/help/reader.md

@@ -4,7 +4,7 @@
 
 **The command**: Reports tab -> Signed dossiers -> **Download GEA Reader for your clients**, or `gea reader --workspace C:\site --out C:\site\GEA-Reader.html`. Send the file once, by any channel (email, a USB stick, the client's portal); send the site's key fingerprint separately - by phone, email or in the contract - as for any dossier. The client opens GEA-Reader.html, drops a dossier on it (or chooses it), and reads the verdict: **Valid** (signed with the site's key, or with a newer key the site's key handed over to), **Valid, but signed by a key you were not given**, or **Not valid** with the reason. Below the verdict: each check, the signer's fingerprint, the key hand-overs, and every file the dossier holds - a report opens in the page as it was signed, a PDF in the browser's own viewer, a table or a log as text, and any file can be saved. A dossier that lists source records by hash without carrying them lets the client choose their copies and checks each against its hash.
 
-**The program**: for a client who wants it installed, **GEA-Reader-Setup-0.75.0.exe** on the release page installs GEA Reader as a Windows program of its own, for the signed-in user, with no administrator rights and nothing of GEA-Program: GEA Reader in the Start menu and on the desktop with its own icon (a white page with a green seal, on blue) and its own taskbar button, and **Check with GEA Reader** on the right-click menu of .zip files (on Windows 11, under Show more options), which opens the dossier at once. It opens the same page in Microsoft Edge's app window with a browser profile of its own (`%LOCALAPPDATA%\GEA-Reader\window`), so a fingerprint the client saves - **Remember this fingerprint**, with whose it is - stays on that computer, and every later dossier signed with that key reads **Valid** with the name the client gave it. `GEA-Reader-portable-0.75.0.zip` is the same program to unzip and run (`GEA-Reader.cmd`). `python\python.exe -m gea_reader --selftest`, in the installed folder, checks the page, the icon, the taskbar identity and the hand-over of a dossier without opening a window.
+**The program**: for a client who wants it installed, **GEA-Reader-Setup-0.76.0.exe** on the release page installs GEA Reader as a Windows program of its own, for the signed-in user, with no administrator rights and nothing of GEA-Program: GEA Reader in the Start menu and on the desktop with its own icon (a white page with a green seal, on blue) and its own taskbar button, and **Check with GEA Reader** on the right-click menu of .zip files (on Windows 11, under Show more options), which opens the dossier at once. It opens the same page in Microsoft Edge's app window with a browser profile of its own (`%LOCALAPPDATA%\GEA-Reader\window`), so a fingerprint the client saves - **Remember this fingerprint**, with whose it is - stays on that computer, and every later dossier signed with that key reads **Valid** with the name the client gave it. `GEA-Reader-portable-0.76.0.zip` is the same program to unzip and run (`GEA-Reader.cmd`). `python\python.exe -m gea_reader --selftest`, in the installed folder, checks the page, the icon, the taskbar identity and the hand-over of a dossier without opening a window.
 
 **What it writes**: the one file, GEA-Reader.html (about 40 KB): the checks, written in the page's own script - Ed25519 (RFC 8032) in its own arithmetic, SHA-256 from the browser - and, when made from a workspace, the site's name and the fingerprints of every key it has signed with (the current one and each retired one from the key history: public halves only; the signing key never leaves `keys\`). The audit log records each download (`reader.download`) and each `gea reader` (`reader.write`) with the fingerprints the reader carried. The reader page writes nothing on the client's computer but the fingerprints a client saves (in the browser's storage for the page): it reads the zip it is given, in memory, and a saved copy goes where the client's browser saves downloads. The installed program also writes the page it opens to `%LOCALAPPDATA%\GEA-Reader\page` (with the dossier inside it when one was right-clicked; removed ten minutes later) and its right-click entry under the user's own registry keys, removed with the program.
 

{gea_program-0.75.0 → gea_program-0.76.0}/gea/help/recorder.md

@@ -2,7 +2,7 @@
 
 > GEA Recorder is the program on the pad: a Raspberry Pi in a sealed box that records the ground channels (geophones, accelerometers, electrode dipoles) through a 24-bit ADC and the rig's WITS0 feed, every sample on one GPS-disciplined clock, into hourly miniSEED files with a SHA-256 beside each and a manifest, and serves one status page on the pad network. Nothing to type: power it and it records. GEA pulls its files in and makes stations of them.
 
-**The command**: the **Seismic** tab, the card **Field recorder**: the box's address on the pad network (`http://192.168.1.50:8780` - the status page shows the address) or the folder of the USB mirror carried to the office, a station name if the site's is not wanted, then **Pull** (a job). GEA fetches the manifest, downloads every file it does not have, checks each against its SHA-256, and makes or updates two stations: the array of the ground-motion sensors (band 8-80 Hz, the sensors' positions from the box's config) and the electrode station (0.01-5 Hz); each sensor's hours are joined in order into one record, nothing re-sampled or filtered. Pull again later: only the new hours come across, and the stations are updated in place. From a terminal: `gea workspace --path C:\site --action field-pull --box http://192.168.1.50:8780`. On the box: `gea-recorder status`, `gea-recorder selftest`; `sudo sh kiosk.sh` once puts the live view full-screen on a monitor on the box's HDMI port from boot - RECORDING in green or what is wrong in red, the clock, the rig's depth, every channel's last minute and the ground sensors' spectrogram, nothing to press - and the same view is at `/live` on the box's page from any browser on the pad network; `sudo sh install.sh` once, from the release's `GEA-Recorder-0.75.0.tar.gz`; the box's README has the parts list, the wiring and the three chrony lines for the GPS clock.
+**The command**: the **Seismic** tab, the card **Field recorder**: the box's address on the pad network (`http://192.168.1.50:8780` - the status page shows the address) or the folder of the USB mirror carried to the office, a station name if the site's is not wanted, then **Pull** (a job). GEA fetches the manifest, downloads every file it does not have, checks each against its SHA-256, and makes or updates two stations: the array of the ground-motion sensors (band 8-80 Hz, the sensors' positions from the box's config) and the electrode station (0.01-5 Hz); each sensor's hours are joined in order into one record, nothing re-sampled or filtered. Pull again later: only the new hours come across, and the stations are updated in place. From a terminal: `gea workspace --path C:\site --action field-pull --box http://192.168.1.50:8780`. On the box: `gea-recorder status`, `gea-recorder selftest`; `sudo sh kiosk.sh` once puts the live view full-screen on a monitor on the box's HDMI port from boot - RECORDING in green or what is wrong in red, the clock, the rig's depth, every channel's last minute and the ground sensors' spectrogram, nothing to press - and the same view is at `/live` on the box's page from any browser on the pad network; `sudo sh install.sh` once, from the release's `GEA-Recorder-0.76.0.tar.gz`; the box's README has the parts list, the wiring and the three chrony lines for the GPS clock.
 
 **Before there is a Pi**: on the same card, **Start the simulated box**: the recorder's own program runs on this computer with its test signal in place of the ADC (a process of its own, its files under `field\sim-box\` in the workspace, its page on port 8781), **Open its monitor** shows the live screen the attendant will see, **Pull from it** brings its files in as stations, **Stop it** closes every file and lists them. **Open the box's monitor** opens any real box's live screen from its address. The kit and the setup install the recorder's program beside GEA for this; a pip install adds it with `pip install gea-recorder`. **From the office, over the internet**: GEA-VPN (`gea help vpn`, Administration) gives every box a private address the office pulls from (`http://10.77.0.3:8780`) through a tunnel from the pad's cellular modem; the box's zip from that card holds `vpn.sh`, run once on the Pi.
 

gea_program-0.76.0/gea/help/tutorial/01-install.md

@@ -0,0 +1,26 @@
+# 1. Install GEA on your computer
+Who: office
+Where: #/
+Takes: 15 minutes
+> The program installed like any Windows program, with the site's folder chosen once.
+
+## Before you start
+You need a Windows PC that will stay on while the site is watched (the office machine, or the doghouse PC), and the setup file for this version, `GEA-Program-Setup-0.76.0.exe`, from the release page on GitHub. No administrator rights are needed: the program installs for you alone.
+
+## Steps
+1. Double-click `GEA-Program-Setup-0.76.0.exe`. If Windows asks whether to run it, choose **Run** - the setup is published by the site, not by a store.
+2. The setup asks for the **site workspace**: the one folder that will hold the wells, the reports, the records, the accounts and the keys. For a new site keep the default or type `C:\site`. For a workspace that already exists, point at it - it is used exactly as it is, its name included.
+3. For a new workspace it asks the **site's name** (`Pad 3`). This name heads every report the program writes; an administrator can change it later in Administration, site settings.
+4. Tick the desktop shortcut and finish. The setup puts **GEA-Program** in the Start menu and an icon in the notification area by the clock.
+5. Start it: the Start menu's **GEA-Program** or the desktop shortcut. The control panel opens in a window of its own; the first time it asks for the first administrator's name and password (lesson 2).
+
+## What happened on the disk
+The program itself is under your user profile (`%LOCALAPPDATA%\Programs\GEA-Program`); the site is in the workspace folder you chose. Those two never mix: a newer setup replaces the program and leaves the workspace as it is.
+
+## You know it worked when
+The control panel window is open with the site's name in its title, and the notification area shows the GEA icon.
+
+## Common questions
+A newer version: from 0.74.0 the program fetches and installs its own new versions by clicking (lesson 22); you never download a setup again. A second site on the same PC: Administration, **Workspaces**, **Make it and open it** - each site is its own folder and its own window.
+
+Help: install, start

gea_program-0.76.0/gea/help/tutorial/02-sign-in.md

@@ -0,0 +1,22 @@
+# 2. Sign in and find your way around
+Who: office
+Where: #/
+Takes: 15 minutes
+> The first account, the four roles, the tabs, the search box, the help panels and the serve window.
+
+## Steps
+1. The first time the control panel opens it shows **First administrator**: this workspace has no accounts yet. Type a name and a password and press **Create and sign in**; this account is the administrator. Keep the password somewhere safe - nobody can read it back.
+2. Sign in. The tabs run across the top (on a phone they stack): Home, Control room, Setup, Sites, Wells, Map, 3D, the engineering pages, Seismic, Patch panel, Files, Alarms, Approvals, Configuration, Reports, Verification, Survey, Tools & ports, Catalogue, Rocks, Jobs, Audit / Update, Administration, Tutorial and Help.
+3. Click **Help** in the top right (the ? button). A short panel appears under the heading of every page saying what it is for, with a **more...** link to the full help page. Leave it on while you learn; turn it off later in your preferences.
+4. Type a well name or a report name in the **search box** and press Enter: the program finds wells, alarms, reports, jobs, configuration entries, patches and schedules by name.
+5. Open **Administration**, **Users**, and add one account per person. The **roles**: *viewer* reads everything and changes nothing; *operator* adds wells and data, declares what the operator knows and writes reports; *approver* signs off well tests and approvals; *admin* manages users, settings, backups and the VPN. A person has one role; give the smallest that does the job.
+6. Look at the window behind the control panel - the **serve window**. It is the server: it prints every sign-in, every job and every stop as it happens. Closing it stops the site; minimise it instead.
+7. Your own settings are under your name, top right: units (field or SI), your time zone, light or dark, the help panels, your password, and **Sign out everywhere else**.
+
+## You know it worked when
+Every person has an account with the right role, and the Audit / Update tab shows a `user.add` line for each.
+
+## Where things are on the disk
+Everything is in the workspace: `wells\` (one folder per well with its source files and records), `reports\`, `records\audit.jsonl` (the audit log), `users.json`, `keys\` (the signing key and the VPN keys - the backup carries them, nothing else does), `exports\`, `installers\`.
+
+Help: start, site

gea_program-0.76.0/gea/help/tutorial/03-site.md

@@ -0,0 +1,22 @@
+# 3. Set up the site
+Who: office
+Where: #/setup
+Takes: 30 minutes
+> The Setup checklist: what the workspace still needs before a report can be handed over, and the site record that holds the wells together.
+
+## Steps
+1. Open **Setup**. The tab carries a badge with the number of required items still to do, and the Home page says which is next. Each item is done when what it asks for is there, not when someone ticks it.
+2. **Site name**: as every report will print it. Set it once.
+3. For each well: the **surface location** (latitude, longitude and the datum the figures are on - NAD27, NAD83 or WGS84, as the permit states), the **reference elevation** (kelly bushing, ground level or derrick floor, in feet, with its source - the completion report, the survey plat), and the **US Well Number** (the API number). With a position declared, **Fetch the ground elevation (USGS 3DEP)** brings the ground elevation there, to check your figure against before declaring.
+4. **Create the site**: its name (`Retama block`), the client, and the wells it holds. A site is the engagement - what one client has - and the Site Report is the one document for it. The **Sites** tab lists every site with a link to its report.
+5. The **backup folder**: a folder on another disk or a share (a folder inside the workspace is refused). Press **Back up now** once and **Schedule daily**. Lesson 21 says how to check and restore one.
+6. **Refresh the reports**: the first run of every report. It is a job; the Jobs tab shows it running and its log.
+7. Press **Go to the next item** until the badge reads 0. Recommended and optional items are listed beside the required ones; a report can be handed over without them, and says what it cannot say yet.
+
+## You know it worked when
+The Setup badge is gone, the Sites tab lists your site with its client and wells, and the Home page shows the wells with a state each.
+
+## The same from a terminal
+`gea checklist --workspace C:\site` prints the list and exits 0 when every required item is done.
+
+Help: setup, sites, site

gea_program-0.76.0/gea/help/tutorial/04-add-well.md

@@ -0,0 +1,24 @@
+# 4. Add a well from a file
+Who: office
+Where: #/wells
+Takes: 20 minutes
+> A file becomes a well with the same reports as any other: a gauge history, a drilling recorder's export, a well log, a catalogue entry.
+
+## What the program reads
+A CSV from a historian (one timestamp column, then the channels); a drilling recorder's export as the rig delivered it (date and time in two columns, then the WITS channels with -999.25 for what the recorder did not have); a LAS or DLIS well log; a SEG-Y record; an Excel workbook; a table an operator exported. The program detects the layout from the file's first lines and says what it found.
+
+## Steps
+1. Put the file somewhere the program may read. An administrator names those folders once: Administration, **File roots** - an import root it may read and an export root it may write. `C:\site\_incoming` is a good import root.
+2. Open **Files**. Browse the import root; beside each file the program says what kind it is (`historian`, `edr`, `las`, `dlis`...). **Preview** shows the first rows as it reads them.
+3. Press **Import** beside the file, name the well (`Well 30636033`, `SWD-1`) and confirm. The file is copied into the well's folder verbatim and hashed; a file already imported is refused by its hash.
+4. Open **Wells**. The new well is listed with a state; click it for its page. The first reports are written by **Refresh** (on Home, or the well page): the drilling record for a recorder's export, the drift and quality reports for a gauge history, the strata survey for a log.
+5. A well from a public dataset: **Wells**, **Add a catalogue well**, choose an entry that carries a downhole gauge series (the Volve production excerpt), name the well inside it and the gauge depth. The Catalogue tab is the map of the 52 datasets the program ships with their provenance.
+6. For a drilling recorder's well, confirm its **depth events** against the daily drilling reports: on the Setup tab, the item names the well; tick it with a note saying which reports you checked. The well report prints who confirmed them.
+
+## You know it worked when
+The well page shows the file under **Sources** with its SHA-256, and the first report under **Reports**.
+
+## The same from a terminal
+`gea workspace --path C:\site --action add-file --file C:\site\_incoming\30636033.csv --name "Well 30636033"` then `gea workspace --path C:\site --action refresh`.
+
+Help: data-in, files, edr, dlis, catalog

gea_program-0.76.0/gea/help/tutorial/05-records.md

@@ -0,0 +1,22 @@
+# 5. A well from its paper records
+Who: office
+Where: #/wells
+Takes: 30 minutes
+> A well known from the regulator's file, the completion report, an inclination survey and an old gas test - entered by clicking, each value kept with the document it came from.
+
+## Steps
+1. **Wells**, **Add a well from its records**: the well's name and, when you have it, the document - the PDF or the scan of the well file. It is kept verbatim and hashed as the well's source.
+2. On the well's page the forms come one at a time, each with a **Source** box: name the document and the date it was filed. Fill **Who and where** first - the API number, the operator of record, the position - which puts the well on the Map and on the Operations & seismicity tab.
+3. **The completion**: the depths, the producing interval, the formation, the nearest lease line.
+4. **Casing**: a link to the Casing & kick tolerance tab, where each string goes in as for any well (lesson 13).
+5. **Inclination survey**: the stations one per line as the form writes them - `1289, 1 1/4` for a measured depth and an inclination of one and a quarter degrees. The program checks the depths and the displacement against themselves.
+6. **Gas well tests**: the shut-in pressure and its depth, the shut-in tubing pressure, the gas gravity, the temperatures, the open flow the document states, and the points one per line: `rate, flowing bottom-hole pressure`. The program fits the deliverability curve and says whether the document's open flow agrees.
+7. Press **Fill the forms with the worked example** to see a public well file's survey and test in the forms before entering your own; then **Write the records review**.
+
+## You know it worked when
+The records review is under the well's reports, every figure with the document and date it came from, and the well is on the Map.
+
+## A well that is not this site's
+A well you are looking at for someone else belongs in a workspace of its own: Administration, **Workspaces**, **Make it and open it** - it opens in a window of its own with its own port.
+
+Help: records

gea_program-0.76.0/gea/help/tutorial/06-well-page.md

@@ -0,0 +1,19 @@
+# 6. The well page: charts, drift, quality and well tests
+Who: office
+Where: #/wells
+Takes: 30 minutes
+> What the program says about a gauge's record and how to read it.
+
+## Steps
+1. Open **Wells** and click a well. The page is a stack of cards; each report has a **more...** to its full text and a **save to...** that copies it to the export root.
+2. **Charts**: choose up to four channels, one per track. Point at the chart for every channel's value at that moment; drag across a stretch to zoom into it; the wheel zooms where you point; double-click shows everything. On a drilling recorder's well the axis switches between **Time** and **Depth**, the depth events are marked where they happened, and each section of recording is a button.
+3. **Quality**: every sample carries a flag and the rule that set it - GOOD, RANGE (outside the engineering range), ROC (rate of change over the limit), FLATLINE, SPIKE, STALE, GAP. The limits come from the gauge's own datasheet in the gauge library; **Tools & ports** lists them.
+4. **Drift**: the residual against the well model and the gauge's aging band. The labels mean what they say: *within the band* is not *correct*, and the report says which.
+5. **Instruments**: a swapped gauge is a new instrument. **Record a swap** (tag, time, old and new serial, certificate id) when one is changed, or **Confirm** a candidate the step detector proposes. **File a certificate** (serial, laboratory, issued, valid until, accuracy, the document); a certificate in its last 60 days raises an alert.
+6. **Well tests**: stable periods found by the criteria in `criteria.json` (Configuration tab); every rejected period names the rule. A test needs **two approvals** - the Approvals tab lists what is waiting; an approver signs, a second approver signs.
+7. **Shut-ins and build-ups**: every shut-in in the record gets a first-look build-up analysis. Save the rock and fluid parameters (q, B, mu, h, phi, c_t, r_w) on the card; without them the result is the slope and p* only.
+
+## You know it worked when
+You can point at the chart and name the moment an alarm fired, and the drift card says which band the gauge is in and why.
+
+Help: charts, quality, drift, instruments, well-tests, transients

gea_program-0.76.0/gea/help/tutorial/07-declare.md

@@ -0,0 +1,20 @@
+# 7. Declarations in one sheet
+Who: office
+Where: #/setup
+Takes: 20 minutes
+> Everything the operator declares about a pad in one spreadsheet, checked against the workspace before anything is written.
+
+## Steps
+1. On **Setup**, press **Download the sheet**. It is an Excel workbook with one table per subject - who each well is and where, the reference elevation, the day rates and the AFE, the fleet, the drill-string runs, the ESP penetrator and drive, the operation windows and catalogues for Operations & Seismicity, the survey program and plans, the casing program, the torque-and-drag string, the hydraulics, frac stage tables, production and decline terms - already filled with what is declared, with a line above each table saying what it takes.
+2. Fill in the blanks in Excel. A row names the well it belongs to; a file a row refers to (a survey, a plan, a stage table, a production file, a catalogue export) is named by its file beside the sheet.
+3. Save it, and on **Setup** press **Check the sheet** and choose it. The program plans every row: **NEW** (nothing declared yet), **CHANGE** (it replaces what is declared - the old value is shown) or **SAME**. One error anywhere and nothing is written; the error names the row and the column.
+4. With no error, press **Write** (the operator role). Every write is an audit line.
+5. Import the same sheet again whenever something changes - rows already declared read SAME and are left alone.
+
+## You know it worked when
+The check lists only SAME rows the second time you check the same sheet.
+
+## The same from a terminal
+`gea declare --workspace C:\site --template C:\site\pad3.xlsx` writes the sheet; `gea declare --workspace C:\site --file C:\site\pad3.xlsx` checks it; add `--apply` to write.
+
+Help: declare