Environmental Digital Model Documentation

Overview

ecbyts (Environmental & Occupational Core Byte Tools) is a platform for Environmental Digital Twins. It creates 3D models of environmental monitoring sites — contaminated areas, water bodies, remediation projects — with linked temporal observation data, scientific analytics, ML-powered recognition, and blockchain-backed data integrity.

What's New

Features delivered between 24 September and 1 October 2026. Each item says what changed, where to open it and which section of this guide covers the rest. The ECBYTS Seal and the compliance presets have their own sections: ECBYTS Seal and Compliance Presets.

ECBYTS (included) AI, paid per use

Signed-in users get the ECBYTS (included) provider as the default AI, with no API key. There are two model categories, both debited from the $ECBT balance on every plan: Basic costs 2 $ECBT per 1,000 output tokens plus 8 $ECBT per 100,000 input tokens; Advanced costs 3 $ECBT per 1,000 output tokens plus 71 $ECBT per 100,000 input tokens. The balance is reserved before the call and settled by the real usage; a repeated or abandoned request is not charged. An optional free model (up to 50 requests per day per account) is available only to whoever accepts that its provider may train on the conversation. Other providers (OpenAI, Claude, Gemini, local models) stay available under AI Assistant > Configure API keys / provider.

Before the first message (chat, command bar or voice) an I agree card shows the approved privacy text with an unchecked box; Not now sends nothing. The acceptance is stored with version, date and language. The Preview before sending button in the chat header (and the tab of the same name in the privacy panel) shows what you typed next to what leaves the browser, with CPF, e-mail and phone replaced by markers such as [CPF_1]. Stored conversation text is erased after 12 months. The credits badge in the header shows the real balance, the included AI usage of the day and the latest movements. Related: AI Assistant, Wallet and Credits.

Payments: Stripe and Mercado Pago

Balance top-ups, the Pro plan and courses can be paid by card through Stripe or Mercado Pago, with the same catalog package in both. Choosing Mercado Pago switches the amount to BRL, converted from USD at the PTAX selling rate plus 3%. Pro is R$ 49 per month (a subscription in both providers) or R$ 490 per year paid once. Mercado Pago asks for the e-mail of your Mercado Pago account. The "Insufficient balance" dialog shows the same value in both providers. The pricing page lists the items paid with balance and the Seal line. Related: Wallet and Credits, Pricing.

Professional registration and model ownership

Verifying your professional council registration (CREA, CRQ, CRBio and others) and registering the ownership of a model cost R$ 25 each, by card, with up to 3 attempts, 12-month validity (then the status shows "Expired") and a 7-day refund. The uploaded proof goes through an automatic technical screening before the AI review; a suspicious file goes to human review, and an AI failure does not consume an attempt. Open it from Cloud > Professional profile, or from the Pro subscription dialog > Verify professional registration. Related: Ownership and Access, Authentication.

Terms and consents

Terms of Use version 1.2 asks every user to accept again; Terms and Privacy Policy are available in the 16 languages of the app, and the privacy policy lists hCaptcha, social logins and AI providers. The consent banner waits for the terms, and advertising measurement has its own consent. AI use has the "I agree" card above, and the free model has a separate acceptance. Related: Data Sovereignty.

Actions tab, HUD corners and phone layout

The Actions tab has a redesigned five-phase stepper, empty cards that explain what is missing, a sunburst in the family colors with path highlight and a grid diagram; it no longer scrolls sideways. The 3D cards (Seal, Equipment, Intangibles) snap to one of eight fixed corners: drag the header or use the grip button ⠿ and its "Move to..." menu; the position is saved in the browser. Below 600 px the cards go to a bottom panel with a button strip, one open at a time, Esc closes. The "Elements by family" panel became an outliner: search, family > element tree, eye toggle, severity and a detail with campaigns and the latest readings. The phone menu gained a tool search. Related: Interface Guide, Customize.

Selection bar and long press

Selecting an element in the 3D model shows an action bar next to the selection: move, rotate and scale modes (W, E, R, G), snap, X/Y/Z, focus, duplicate, hide, properties, more actions, delete and done. On desktop it sits at the top of the scene; below 600 px it moves to the footer with 44 px targets. Right-click an element (or long-press it on a phone) for its context menu; the gizmo is 40% larger on touch; Esc with a menu open only closes the menu. Related: 3D Scene, Keyboard Shortcuts.

Charts with Data, Edit and PNG

Charts show a Data / Edit / PNG bar. Data opens the underlying table with search and CSV export; Edit changes the color and visibility of each series or slice (saved per chart in the browser); PNG downloads the image. It is available in the Actions tab relation charts, the five Cost Analysis charts (the time axis now shows years), the EIS ring, the Analytics histogram and scatter (Data and PNG only) and the EVA PV/EV/AC and S-curves. Related: Analytics, Cost Analysis.

Ecby suggests the next step

Next to the Ecby mascot a box suggests one next step at a time (import, violations, trends with Mann-Kendall, interpolation, results per campaign, project location, data quality, cross-section, geology, report, sheet, presentation and steps per family) with a play button that opens the module. It hides after 8 seconds and pauses while the pointer or focus is on it. Turn it off with "Don't suggest again" or the proactive AI button. Related: AI Assistant.

Tours Trail, proof of completion and selling courses

The free ECBYTS Tours Trail course runs 10 guided tours and a final assessment (pass mark 80%). The proof of completion, a two-page PDF with QR and a performance report, costs USD 1 = 100 $ECBT; the name is confirmed before acceptance and the proof of completion shows on any device of the same account. Open it from the command palette ("Tours Trail"), the Home quick access, the tour picker or Learn. The tour ?tour=monetizacao ("How to earn with ECBYTS") shows how to price (minimum R$ 4.99), publish and receive 80% of each sale in $ECBT; "Enable payouts" next to the price in the lesson editor leads to Stripe Connect. Related: Guided Tours, Libraries Marketplace.

3D visuals and plume vertical reference

The scene uses ACES tone mapping, hemisphere light and a gradient background. Labels come in three layers with a budget of 14 on phones, show a dot in the family color and rotate between families. Each contamination layer of the interpolation can be bounded vertically: below or above the water table, the ground surface, a geological contact, a fixed elevation or a lake or river bottom, with an optional confining base and LNAPL top or DNAPL base anchoring; the plan area can follow the outline of an element. Z-X and Z-Y vertical sections of the plume are available. Open Analyze > Interpolation > layer card > Vertical reference. Related: Interpolation, 3D Labels.

Linked responsibles and auditor

In the Project tab, the technical responsible and auditor fields can be linked to an ECBYTS account: invitation, acceptance and withdrawal. Campaigns inherit the linked responsibles, and the ECBYTS Seal uses them for the proof bands. Related: Campaigns, ECBYTS Seal.

Faster start and ticker

The Home screen appears before the 3D model loads, and the loading overlay is limited to the Model tab. With a saved session the header shows your initials and "Connecting..." instead of "Sign in" while the session is restored. On small screens, slow networks or Save-Data, heavy 3D files are replaced by procedural meshes. The ticker settings explain that values are recalculated when the data changes (there is no clock), that sensors with auto-refresh bring readings every 5, 15 or 30 minutes, and that the bar is hidden on the Home screen and in Data Studio. Related: IoT Sensors, Authentication.

News on the public site

The public site has a News section with a list, article pages, RSS and sitemap, linked from the landing page, plans and courses. The first article presents the ECBYTS Seal.

Layouts: Default, Focus, Analysis and My arrangement

Open View > Layouts&, the command palette or Ctrl+Shift+L to rearrange the screen in one step. Default opens the side and bottom panels at their default size and returns the 3D HUDs to their default corners; Focus closes the side and bottom panels and leaves only the scene; Analysis opens everything with a taller bottom panel for tables and charts. Save current arrangement keeps your own layout as My arrangement. After applying a layout, Undo stays available for 10 seconds.

Data and PNG on the 3D HUD cards

The 3D HUD cards for EIS, costs, ECBT and violations now carry the same Data / PNG bar as the charts. It floats in the corner of the card and appears on hover, on keyboard focus or with Shift+F10. Data opens the table with search and CSV export, and the costs card lists every item, not only the three that fit on the card; PNG downloads the image of the card.

Terms 1.2, Purchase Contract and proof of acceptance

Terms of Use 1.2 and Privacy Policy 1.2 ask every account to accept again, and a new Purchase Contract page, in the 16 languages of the app, covers balance top-ups, the Pro plan and courses. Under the right of withdrawal, within 7 days of a purchase the full amount is refunded to the same card. Each acceptance is now recorded by the server with date, terms version, IP address and browser, as proof of the click; an account can read only its own records. The pricing page shows the AI rates, the AI data notice and the link to the contract.

Quick Start

1. Open the application at https://ecbyts.com or localhost:4000 for local development.
2. On first visit, the Welcome Screen lets you choose an init mode: Random Model, Map Picker, Last Location, or Blank.
3. Use the toolbar at the top to access grouped actions: File, History, Insert, Libraries, View, Analyze, and More.
4. Click Insert > Add Element to create your first environmental element (well, plume, lake, etc.).
5. Add Campaigns to define sampling events, then add Observations (parameter + value + timestamp) to your elements.
6. Use the 3D viewport to visualize your site. Rotate (left-click drag), pan (right-click drag), zoom (scroll).
7. Go to Optimize tab for analytics, neural networks, and guided environmental workflows.
8. Export your model using File > Export to save as an ECBT key.

Interface Guide

Layout

The application uses a CSS Grid layout with five main areas:

• Toolbar (top) — Flat toolbar with permanent groups and progressive-disclosure dropdowns.
• Left Panel — Element list organized by family. Click an element to select it in the 3D view.
• 3D Viewport (center) — Interactive Three.js scene showing your environmental model.
• Right Panel — Property inspector showing details of the selected element, observations, and campaigns.
• Constellation HUD (bottom) — Tabbed bottom bar with analytics charts, data entry matrix, cost analysis, timeline ticker, and more.

Panel Reference

These screenshots summarize the main panels and navigation surfaces used by most modules and submodules:

Toolbar Groups

The toolbar uses a flat layout with permanent groups and dropdown menus for progressive disclosure:

Two additional toolbar surfaces appear contextually: Voxel Controls are shown only when voxel mode is active, and the Edit Ribbon replaces the main toolbar while shape editing is in progress.

View Modes

The application has a View Router that manages four distinct modes, switchable via the toolbar or keyboard:

Element Families (PDPL-U / PDPLU)

Elements are the building blocks of your environmental model. Each element belongs to a family that determines its 3D representation, available properties, and behavior. The classification follows the PDPL-U / PDPLU model.

In ecbyts, PDPL-U and PDPLU refer to the same organizing model: Ponto, Data, Parametro, Leitura, Unidade. This structure underpins the platform's element families, tabular observation views, CSV exports, and the broader organization of environmental records and site entities.

When you see PDPLU in the bottom Constellation HUD, it is the same concept rendered as a flat observation table and export format.

Campaigns

A Campaign represents a field sampling event — a specific date when a team collected data from multiple elements. Campaigns organize observations chronologically.

• Each campaign has a date, team name, and description.
• Observations are always linked to both an element and a campaign.
• Use the Timeline Ticker in the Constellation HUD to navigate between campaigns and see how data changes over time.
• Create campaigns via Insert > Add Campaign or through the right panel.

Observations

An Observation is a single measurement at a specific point in time: a parameter (what was measured), a value (the result), and a timestamp (when). Observations are the core data of the environmental model.

• Parameter: What was measured (e.g., Benzene, pH, Dissolved Oxygen). Supports 30+ built-in parameters plus custom ones.
• Value: The numeric result with units (e.g., 0.005 mg/L). Unit conversion uses a 90+ unit catalog.
• Timestamp: When the measurement was taken (linked to a Campaign).
• Custom Fields: Additional context like sample depth, detection limit, fraction, and preservation method.
• Observations drive analytics: trends, exceedances, interpolation, compliance checks, and EIS scoring.

Scenes

Scenes are saved camera viewpoints and display configurations. They let you quickly switch between different views of your model.

• Save the current camera position, zoom, and rotation as a named scene.
• Scene snapshots are included in reports and the storyboard sequencer.
• Create scenes via Insert > Add Scene.

Stamps & Edges

Stamps are compliance or status tags attached to elements. Edges are directed relationships between elements, forming a knowledge graph of your environmental site.

Stamps

20+ predefined tags for element annotation:

• compliance_ok, compliance_fail — Regulatory compliance status.
• priority_high, priority_medium, priority_low — Prioritization levels.
• retest_required, archived, under_review — Workflow status markers.
• Stamps are visible in the element list and included in ECBT exports.

Edges

15+ directed relationship types between elements:

• monitors — Well monitors a plume or area.
• sources_from, discharges_to, flows_to — Hydrological connections.
• contains, part_of — Spatial containment hierarchy.
• occurred_in, involved_in — Incident-area associations.
• inhabits, supplies, treats, adjacent_to — Ecological and operational links.

Unit Conversion Engine

90+ units across 12 dimensions with automatic conversion between compatible units. When observations use different units for the same parameter, the engine converts values transparently for analytics and compliance checks.

3D Scene

The 3D viewport is powered by Three.js and renders your environmental model in real-time.

Camera Controls

Visualization Options

• Grid — Toggle reference grid on/off (View tab).
• Layer Visibility — Show/hide specific element families.
• Labels — Four categories of CSS2D billboards: element names, observation values, geology layers, and model title.
• Terrain — Enable interpolated terrain surface from elevation data.
• Symbology — Apply visual overlay profiles for standardized site mapping.
• Cursor Projector — Real-time coordinate display projected onto terrain and meshes.

3D Labels

In-scene element labeling using CSS2DRenderer billboards that always face the camera.

• Four label categories: element names, observation values, geology layers, and model title.
• Dynamic visibility based on zoom level and element selection.
• Labels update in real-time when observations or element properties change.
• Toggle via View > Labels in the toolbar.

Symbology Profiles

Standardized visual mapping profiles that control how elements are rendered in the 3D viewport. Symbology profiles ensure consistent visual communication across environmental site investigations.

• Profile-based rendering — Switch between symbology standards (ABNT, CETESB, custom) to change element colors, icons, and 3D shapes globally.
• Layer-aware styling — Each element family has configurable visual rules based on observation values, compliance status, and metadata.
• Legend generation — Auto-generated map legends matching the active symbology profile for reports and drawing plates.
• Custom profiles — Create organization-specific symbology standards via JSON configuration.

Analytics

The analytics module provides scientific analysis tools for environmental monitoring data, organized as a multi-viewport workspace.

Available Analyses

• Time Series Charts — Plot observation values over time with Chart.js. Compare multiple parameters and elements.
• Mann-Kendall Trend Test — Statistical test for monotonic trends in environmental data. Identifies increasing or decreasing contamination patterns.
• Predictions — Forecast future values based on historical trends using regression models.
• Cost Analysis (CAPEX+OPEX) — Roll up remediation costs by project, fiscal year, and cost category with L1–L4 aggregation.
• GA Optimization — Genetic Algorithm-based prescriptive optimization for spatial sampling network design, using Kriging variance minimization.
• Histograms — Frequency distribution of observation values.
• Scatter Plots — Bivariate analysis across parameters or elements.
• Cross-tabulation — Pivot-table analysis of multi-dimensional observation data.
• Violations Timeline — Compliance breach tracking across time.
• Temporal KPI (D2) — Time-series scoring for data density and coverage.

Parameter Filter & Radar (FEAT-FILTER-RADAR-001)

Aggregation engine that groups environmental parameters into 7 canonical classes and computes per-element radar charts for rapid multi-contaminant assessment.

• 7 canonical groups — VOC, SVOC, Metais (metals), Físico-Químicos, Hidrocarbonetos, Pesticidas, Nutrientes. Based on EPA QAPP §3.4.2.
• 6 aggregation functions — mean, median, max, min, P95 (EPA-240/B-06-003), standard deviation — configurable per group.
• O(1) element index — buildElementGroupIndex pre-computes group membership so radar data resolves in constant time regardless of observation count.
• Per-element radar — computeElementRadarData returns 7-axis scores normalized to CETESB VP/VI thresholds for immediate visual risk classification.
• Drill-down (Phase 2) — Canvas 2D radar renderer + lateral drill-down panel + i18n 16 locales + synchronized 3D highlighting. Pending.

Scenario Simulation

Probabilistic environmental scenario modeling using Monte Carlo and Latin Hypercube Sampling (LHS). Evaluate remediation strategies under uncertainty before committing resources.

• 8 pre-defined scenarios — BTEX plume, heavy metals, chlorinated solvents, PAH, nitrate, GHG, effluent, leachate.
• 25+ remediation decisions — Pump & Treat, PRB, MNA, SVE, and more.
• P10–P90 cost ranges — CAPEX + OPEX with confidence intervals.
• Composite score — compliance×30 + noFailure×20 + costEfficiency×20 + health×15 + speed×15

Calculator

The Calculator is a reusable filter pipeline for computing environmental metrics, compound rules, and parameter ratios from live model data.

• Metrics — Compute aggregate values (mean, max, exceedance count) across elements and campaigns.
• Compound Rules — Boolean or threshold-based rules combining multiple parameters (e.g., "Benzene > VI AND pH < 5").
• Ratios — Parameter-to-parameter ratios for diagnostic analysis.
• Hypotheses — What-if scenario definitions that feed neural network predictions.
• MAC Curves — Marginal Abatement Cost curves for remediation prioritization.

Calculator items are defined via the Data Entry Matrix in the Constellation HUD and persist in the model.

Import / Export (ECBT)

The ECBT format is the unified serialization format for ecbyts models. It supports both simple and blockchain-backed models.

Export

• Export Key — Generates a compact ECBT string that encodes the entire model (elements, campaigns, observations, scenes, edges, calculator, constants, interpolation layers, and more). Copy and share as text.
• Export JSON — Full model as a JSON file for programmatic use.
• Download — Save the model as a downloadable file.

Import

• Import Key — Paste an ECBT key to restore a full model. Legacy ECO1 keys are also accepted for backward compatibility.
• Import JSON — Load a previously exported JSON file.
• Spreadsheet Import — Bulk import from XLSX/CSV files using the ingestion wizard.
• DXF Import — Import CAD site plans as Spatial Blueprint elements.
• URL Import — Shared links use #key=ECBT.A0000001-...-10000000A.TBCE so the model is not sent in the HTTP request. Legacy ?key= links remain readable. A fragment is not encryption: share only with authorized recipients.

Simple (A):     ECBT.A0000001-{families}-{salt}-{checksum}-{payload}-10000000A.TBCE
Blockchain (B): ECBT.B0000001-{families}-{keyId}-{prevHash}-{merkle}-{signature}-{salt}-{checksum}-{payload}-10000000B.TBCE
Compressed (C): ECBT.C0000001-{families}-{salt}-{crc32}-{payload}-10000000C.TBCE

Files Module

Cloud-based file management integrated with Supabase Storage. Attach documents, images, and reports to your environmental model with full versioning and access control.

• Per-project storage — Files are organized by project with automatic folder structure.
• Drag & drop upload — Upload files directly from the file manager panel. Supports images, PDFs, DOCX, XLSX, DXF, and more.
• Inline preview — Preview images and documents without downloading. PDF and image files render inline.
• Element attachments — Link files to specific elements (e.g., well logs, lab reports, photos).
• Quota-aware — Storage usage counts against your plan quota. Free tier: 50 MB. Pro: 5 GB. Scale: 50 GB.

IFC / BIM Export

Export your environmental model to IFC4 format (ISO 16739-1:2018), the international BIM standard for integration with Autodesk Revit, ArchiCAD, and BIM 360.

• Each element exported as an IfcBuildingElementProxy with full 3D placement.
• No external dependencies — pure STEP text output (ISO 10303-21).
• Axis conversion: Three.js Y-up → IFC Z-up automatically handled.
• Property sets: ecbyts_Metadata (family, id, name) and ecbyts_Observations (last observation per parameter).

Power BI Integration (BI v1)

Tabular BI API designed for analytics tools like Power BI. Endpoints expose a star-model friendly structure.

• GET /api/bi/v1/schema — Table dictionary and column types.
• GET /api/bi/v1/dim_elements — Elements dimension.
• GET /api/bi/v1/dim_campaigns — Campaigns dimension.
• GET /api/bi/v1/fact_observations — Observations fact table (filterable by date, element, campaign, parameter).
• GET /api/bi/v1/fact_edges — Element relationship facts.

Interpolation

Spatial interpolation creates continuous surfaces from point observations, essential for mapping contamination plumes and terrain.

• IDW (Inverse Distance Weighting) — Simple, fast interpolation weighted by distance. Built-in, zero dependencies.
• RBF (Radial Basis Functions) — Smooth interpolation using radial basis functions. Loaded on demand via CDN.
• Kriging — Geostatistical interpolation providing best linear unbiased estimates with uncertainty quantification. Loaded on demand via CDN.
• Terrain Interpolation — Generate terrain surfaces from elevation data points.

Potentiometric Maps & Plume Generation

Automated spatial analysis from monitoring campaign data, generating potentiometric surfaces and contamination plumes.

• Potentiometric map — Generated from water_level observations using Kriging or IDW interpolation. Shows groundwater flow direction and hydraulic gradient.
• Contamination plume generation — Create plume boundaries from campaign concentration data, automatically identifying hotspots and extent.
• Contour isolines — Labeled contour lines with configurable intervals for precise value mapping.
• Coordinate deduplication — Handles co-located wells (multiple wells at similar coordinates) by averaging or selecting representative values.
• Water-level series with explicit datum — Each water_level observation keeps its raw value, unit (unitId, converted to metres through the unit catalog), ISO date, campaign and quality flags. The vertical datum is read from the observation (datum: msl or depth_below_reference with referenceElevation or the well's coordinates.elevation); an observation without a datum is excluded and listed as an issue (datum_missing) — it is never silently treated as an msl elevation; the legacy assumption only applies when the caller explicitly passes defaultDatum, and every such point is flagged datumAssumed. Observations without a parseable date, without a reference elevation for depth readings, or with a unit that cannot be converted to metres are listed as issues and never enter the curve.
• Hydrograph and interpolation — The report figure Hydrograph (water level per well) draws one curve per well (or all wells) from the same series, in metres msl with the declared datum in the footer; the Interpolation panel's water-table layer reads heads through the same module (unit converted, datum resolved) instead of the raw numeric value.
• Campaign comparison and export — The latest reading per well feeds the potentiometric figure; the command palette entry Export water-level series (TSV) downloads the whole series; two campaigns can be compared well by well (head difference in metres), and the series exports as TSV preserving raw value, unit, datum, reference elevation, conversion note, date, campaign and author (core/hydrology/_headSeriesPure).

Voxel Modeling

3D subsurface modeling using volumetric voxels for contamination plume visualization and geochemical analysis.

• Discretize the subsurface into a 3D grid of voxels, each holding parameter values.
• Apply color ramps and opacity thresholds to visualize contamination extent in three dimensions.
• Combine with interpolation layers for integrated subsurface analysis.
• Voxel data is persisted to IndexedDB for fast reload.

Neural Networks

Custom neural network module for predictive modeling of environmental data.

• SimpleNN — Vanilla JavaScript neural network implementation (no external frameworks). Trained on calculator metric values from real element observations.
• Web Worker Training — Training runs off the main thread to keep the UI responsive.
• What-If Engine — Run scenario predictions by modifying input parameters and observing predicted outcomes.
• Plume Connector — Connect trained networks to plume visualization for dynamic contamination prediction.
• Named NN instances are persisted to IndexedDB and included in ECBT exports.

Fine-Tuning Pipeline

Domain-specific fine-tuning pipeline for training language models on environmental data. Uses Qwen2.5 as the base model with LoRA adapters for efficient specialization.

Pipeline Stages

ML Recognition

Machine learning modules for automated image analysis and environmental feature detection.

• Image Classification — Classify aerial or site images using neural network models.
• SLIC Superpixels — Segment images into visually coherent regions for pre-processing.
• YOLOS Object Detection — Detect environmental features (tanks, wells, buildings) in aerial imagery.
• SAM (Segment Anything) — Interactive segmentation for precise boundary extraction.

Aerial Georeferencing

Workflow for georeferencing user-owned aerial or satellite images onto the 3D model.

• Interactive GCP placement — Click and drag Ground Control Points on both the image and the map (minimum 3 points required).
• EXIF GPS bootstrap — Optionally reads GPS coordinates from JPEG EXIF metadata for initial placement.
• AI "Suggest Location" — Uses an LLM provider (OpenAI, Claude, or Gemini) to suggest the geographic location from image content.
• Live map preview — Real-time overlay of the image on the map with opacity slider and satellite toggle.
• Applies a georeferenced boundary element with the image as an overlay texture rendered in the 3D viewport.

Blockchain Integrity

Data integrity is enforced through cryptographic primitives, ensuring environmental data cannot be tampered with after collection.

• SHA-256 Hashing — Every data point gets a unique cryptographic fingerprint.
• ECDSA Signatures — Digital signatures prove data authorship and prevent forgery (P-256 via Web Crypto API).
• Merkle Trees — Efficient verification of data sets — any modification invalidates the tree root.
• Hash Chains — Sequential linking ensures chronological ordering cannot be altered.
• AES Vault — Encrypted storage for sensitive key material.

EIS — EnviroTech Integrity Score

The EIS (EnviroTech Integrity Score) evaluates the quality and trustworthiness of an environmental model using the 3CTA+ framework — a non-compensatory geometric weighted mean across 6 axes.

Score Axes

Score Interpretation

• ● ≥ 4.50 — High integrity. Model is reliable for decision-making.
• ▲ ≥ 3.50 — Moderate integrity. Review flagged axes before use.
• ◆ < 3.50 — Low integrity. Significant data quality issues.

ECBYTS Seal and Declaration

The ECBYTS Seal is a QR card that publishes, for the loaded model, the net ECBT balance, the EIS data-integrity score, the SDG ring and three proof bands (Technical Responsible with ART, independent audit, environmental agency via the Legal Representative). Anyone who scans the QR opens the public verification page with the registered numbers.

Levels, who issues and what it costs

There are three levels. 1. Declaration: numbers only. 2. RT: the Technical Responsible attaches the ART over the issued numbers. 3. Agency: the Legal Representative attaches an acceptance document from the environmental agency that cites that ART (a filing receipt is not acceptance). The independent auditor is optional from level 2 and never changes the level; the auditor cannot be the RT or the Legal Representative of the same dataset. Every attachment points to the seal id and to the fingerprint of the numbers: if the data changes, the attachment becomes outdated and the seal falls back to Declaration until a new ART.

A seal of a random model is a free simulation for any signed-in account, with fictitious responsibles, and never counts as a seal. A seal of real data is issued only by the data owner with an active Pro account, at no cost to the owner, and only after an RT has accepted. Each responsible (RT, auditor, Legal Representative) pays USD 1 (100 $ECBT) from their own balance or by card when accepting; a partitioned dataset needs one paid attestation per partition and role.

Life cycle: after the last acceptance the seal is provisional for 7 days, the withdrawal window in which a responsible may get the USD 1 back and leave the seal. Then it is valid for 12 months. The owner may revoke it (the public record stays, marked revoked) or issue a new version that supersedes the old one. When the model changes after issuance, the card shows the seal as outdated and asks for a new issuance.

Where to find it

The card appears on the Home screen, in the Actions tab and over the 3D model. Its buttons: Rule (choose the evaluation rule), i (how the seal is calculated), the gear (appearance: show or hide the EIS ring, SDG ring, proof bands and drop; numbers and QR do not change), My seals (issued seals, state, who sees what, invitations), attachments and Issue. Hovering or clicking a ring sector explains it and leads to the data. The guided tour opens with ?tour=selo-ecbyts.

How the numbers are calculated, step by step

The seal uses the same engines as the EIS and ECBT panels, with stricter rules. The evaluation rule (AURUM, GAIA and the others) does not change the ECBT or the EIS: it sets the mandatory SDGs, the sub-preset of each front and the label printed on the seal. All formulas below are in the code; the worked examples at the end of this section are computed by that same code.

Step 1. Active compliance preset

The active compliance preset provides the EIS weights. With no preset active, the default weights apply (T 3, A 3, Cp 2, Ty 2, Cs 1, Cm 1). If the binding is invalid, the preset is revoked or its contentHash differs from the one recorded at activation, the context is blocked and the seal shows no numbers. A preset without EIS weights (for example the CETESB risk preset) leaves the seal without EIS.

Step 2. EIS (data integrity, 1 to 5)

Six core axes get a score from 1 to 5 from the observations of all elements. When an axis has no evidence it falls back to a heuristic score, which is shown as such in the examples. The four progressive axes (V, U, Un, Ex) are drawn on the ring but do not enter the number.

T  (traceability)  m = mean credential multiplier of the readings
                   (common 1.0 · professional 1.2 · pos_graduado 1.4 · mestre 1.6 · doutor 2.0)
                   m >= 1.8 ’ 5 · >= 1.4 ’ 4 · >= 1.2 ’ 3 · >= 1.0 ’ 2 · else 1
                   +0.5 if >= 90% of readings have an author (cap 5)
                   no readings ’ 4 if any element has name and description, else 3
A  (accuracy)      sensors: operational / total; else readings within limits
                   (high relative uncertainty > 50% counts half);
                   ratio >= 0.95 ’ 5 · >= 0.80 ’ 4 · >= 0.60 ’ 3 · >= 0.40 ’ 2 · else 1
                   calibration: calibrated +0.5 · expired 0.5 · uncertain 0.7 · unknown 1.0
                   no evidence ’ 5 if any element has coordinates, else 2
Cp (completeness)  executed / planned readings of the campaigns
                   >= 0.95 ’ 5 · >= 0.80 ’ 4 · >= 0.60 ’ 3 · >= 0.30 ’ 2 · else 1
                   no numeric plan ’ 4 if there is a boundary element, else 3
Ty (timeliness)    median age of the readings at the reference date (days)
                   <= 30 ’ 5 · <= 90 ’ 4 · <= 180 ’ 3 · <= 365 ’ 2 · else 1
Cs (consistency)   readings whose unit is in the unit catalog / readings with a unit
                   >= 0.95 ’ 5 · >= 0.80 ’ 4 · >= 0.60 ’ 3 · >= 0.40 ’ 2 · else 1
                   no readings ’ 2
Cm (comparability) (mapped parameters + readings in the default unit) / (2 × readings)
                   same bands as Cs; without a parameter catalog ’ 4 if >= 2 campaigns, else 2

EIS =   axis_i ^ (w_i / £w)      rounded to 2 decimals (geometric mode)
verdict: >= 4.50 Audit Ready · >= 3.50 Management Ready · else Critical Data
º (confidence) = EIS / 5         clamped to [0, 1]

The weighted geometric mean does not let a strong axis hide a weak one as much as an arithmetic mean would. "Critical Data" (EIS below 3.50) is printed next to the EIS. The veto mode (EIS = 0 when T or A is 2 or less) exists in the engine but is not applied on the seal path: the Rule screen lists it as planned.

Step 3. ECBT of the seal (net balance)

The main number is the net balance of realized assets minus environmental liabilities. Liabilities are the CAPEX and OPEX recorded on the elements (or the ERP chain when enabled), with a fixed 25% uncertainty. Natural capital never enters the main number: it goes to a separate informative line (step 4). The band is the root-sum-square uncertainty (GUM) widened by data confidence º.

V_net     = £ realized assets  £ liabilities           (currency of the model)
u_i       = |value_i| × u_frac_i                         (liabilities: u_frac = 0.25)
U         = ( £ u_assets² + £ u_liabilities² )           (GUM, root-sum-square)
widener   = 1 + 2 × (1  º)                               (º = 1 ’ ×1 · º = 0.5 ’ ×2 · º = 0 ’ ×3)
band      = [ V_net  U × widener ; V_net + U × widener ]
ECBT %    = V_net / denominator × 100                    (only with a persisted denominator)

The ECBT percentage divides the net value by the denominator STORED in the model (model.financial.denominator: revenue, EBITDA or market value, with currency, fiscal year and source). The random model stores the net revenue of the generated income statement (source "ERP-derived"). With no stored denominator, or with a currency different from the net value, the seal prints ECBT % n/d and the absolute net value (for example "net R$ 1.0 mi"). Revenue, EBITDA, market value and similar figures typed only in the session are ignored on purpose: whoever verifies the seal could not reproduce the percentage. Fines and the fine impact score stay in the ECBT panel and do not enter the seal.

Step 4. Natural capital line (separate)

Natural capital is valued per element: family × area × R$/m² from the seed catalog (tier "expected", unless a library or the user overrides it). Area comes from the element, or from its polygon (shoelace formula), or for rivers from path length × width (5 m by default); a tree or animal is valued per unit. Each entry carries 30% uncertainty. Only catalog values or values with attached evidence are eligible; a value typed without evidence is declared, stays out and is reported only as a warning.

value_e   = area_e (m²) × price_family (R$/m²)             (individual: price per unit)
NC        = £ eligible value_e                            (provenance catalog or evidenced)
U_NC      = ( £ (value_e × 0.30)² ) × (1 + 2 × (1  º))
printed   = "natural capital +R$ & (separate)"           (never added to V_net)

Step 5. Intervention ratio and severity

For each point and parameter only the most recent reading counts, because the seal declares the current condition. The reading is converted to the unit of the intervention value (VI) of the regulatory matrix; the VI is the smallest intervention threshold (VI, CMA or severity "intervention"), never a minimum bound such as pH. The name is honest: it is a compliance ratio, not a toxicological hazard quotient.

ratio_i   = reading_i / VI_i
R         = min( max ratio_i ; 1 )                        (0 when no reading has a VI)
alert     = any ratio_i >= 1                              ("ALERT: n readings in Intervention")
S         = max( 1  º ; R )
label     = S >= 0.7 high · S >= 0.4 medium · else low

Step 6. SDG ring

Each of the 17 SDGs gets only its impact score (0 to 1) from the SDG overlay. Below the threshold (0.5 by default) the sector points inward in red (harm); above it points outward in the SDG color (contribution). Data coverage and confidence never add to the impact: they become the data quality and the evidence tier. The mandatory SDGs come from the rule (AURUM requires all 17); a mandatory SDG without data is drawn dashed as "no data" and never disappears.

s = impact / 5            t = threshold (0.5)
harm:          s < t   magnitude = (t  s) / t
contribution:  s >= t  magnitude = (s  t) / (1  t)
quality       = ( coverage/5 × confidence/5 )            (one of them zero ’ quality zero)
tier          = quality >= 0.6 measured · >= 0.3 estimated · else claimed
SDGs covered  = SDGs with an impact score                 (goes into the AURUM line)

Step 7. Proof bands

Each dataset (campaign) weighs as many observations as it has (an empty campaign weighs 1). A dataset counts for the RT band when it has an RT and a valid ART number (8 to 24 letters or digits after removing punctuation); for the audit band when, on top of that, an auditor who is neither the RT nor the Legal Representative attached a report with a SHA-256 hash; for the agency band when, on top of the ART, the Legal Representative recorded the agency document. Pending acceptances do not count.

band %   = £ observations of the datasets that qualify / £ observations × 100   (rounded to 0.1)
painted  = clockwise from the top left, in proportion to band %

Step 8. Rule, fronts and the AURUM line

Each rule is composed of one sub-preset per front (health risk, soil and groundwater guidance values, water, air, GHG method, occupational exposure). The default of each front is the most restrictive available sub-preset (limit fronts) or the newest version of the same family (method fronts). The RT may only tighten a limit or move a method to a newer version, always with a justification; AURUM locks everything. The composition gets an FNV-1a 32-bit hash that the server recomputes at issuance and refuses when it differs. Every seal also prints its result on the AURUM 1.0 scale, so a GAIA seal shows how it would look under the strictest rule.

fronts line   = "front=sub-preset;& · hash8"              (fronts sorted by id)
hash8         = FNV-1a 32 bits of {"rule":"NAME VERSION","fronts":[[front, id, version], &]}
AURUM line    = "AURUM 1.0 · ODS a/17 · frentes b/6"     (a = SDGs with impact, b = composed fronts, "n/a" excluded)
comparable    = same rule and same MAJOR version          (trend and supersede skip other majors)
variant label = "REGRA GAIA 1.0 · PERSONALIZADA · a1b2"  (owner) or "· RT · a1b2" (RT); a1b2 = first 4 hex of SHA-256

Step 9. Formatting printed on the seal

ECBT %: whole number from 10, one decimal from 1 to 10, two decimals below 1, "<0,01%" below 0.01, with a sign. Money: thousand, million and billion abbreviations with one decimal under 100. EIS: one decimal. The QR of a preview carries the numbers in the link and the verification page states "preview not registered"; a registered seal carries only its id.

Step 10. Issuance, fingerprint and server recalculation

At issuance the browser sends a snapshot of up to 8 KB with the printed fields (ECBT, net value, EIS, verdict, intervention line, AURUM line, rule label, fronts line, site coordinates). The server stores its SHA-256 as the fingerprint; the public page recomputes it and says whether the record is intact. Any change in the numbers produces another fingerprint and asks the responsibles to accept again.

The reproducible recalculation (shadow mode) rebuilds the numbers from the model data instead of trusting the browser: personal keys are removed, the same engines run, and each recalculated field (ECBT, net value, EIS, verdict, AURUM line) is compared with what the browser sent. A divergence is recorded, not blocked. After each issuance the browser sends this data snapshot, compressed, to the server function seal-recompute, which runs the same engine bundle and records the status (match, mismatch, unsupported, too large, error), the data hash and the engine hash. The server keeps only the hashes, never the model data, and compares against the numbers stored at issuance, not against what arrives with the data. Issuance and the public page do not depend on it yet. Its reproducible fingerprint is:

dataSha256       = SHA-256( canonical JSON of the data snapshot )   (keys sorted, no personal data, no images)
catalogSha256    = SHA-256( canonical JSON of the effective natural capital catalog )
reproFingerprint = SHA-256( canonical JSON of { schema: "ecbyts.seal.repro/1", dataSha256, engine,
                                                rule: { name, version, frontsLine }, catalogSha256, fields } )

Known limits

Read the seal with these limits in mind: the ECBT percentage exists only when the model stores a denominator; several EIS axes fall back to heuristics when the model lacks plans, parameter catalogs or QA/QC evidence; the discount rate, maximum data age, veto, server-side credential check and ±1 weight robustness test are shown on the Rule screen as planned and do not change the numbers yet; liabilities are a management estimate, not an accounting provision; natural capital uses unit value transfer from global studies.

The tables below are generated from the code by scripts/docs/gen-seal-presets-doc.mjs: every rule, field, front and sub-preset with its version and definition hash, the version history, and the worked examples. A CI check fails when the code changes and this page was not regenerated.

Evaluation rules and versions (generated) / Regras e versões (gerado do código)

Adjustable fields / Campos ajustáveis

• RT changes need a justification of at least 30 characters / justificativa mínima do RT. AURUM locks every field.

Locked for everyone / Travado para todos

• applied / aplicado — Norma e valores orientadores (CONAMA 420 e a norma do estado)
• planned / previsto — Fronteira mínima: área, elementos, matrizes e período
• applied / aplicado — ECBT sem capital natural no número principal
• planned / previsto — Veto do EIS: confiabilidade ou exposição ≤ 2 dá crítico
• planned / previsto — Credencial do RT validada no servidor
• planned / previsto — Teste de robustez com pesos ±1

Fronts and sub-presets / Frentes e sub-presets

• Server mirror / espelho no servidor (20261001090000_ecbyts_seal_sub_presets.sql, 20261001130000_ecbyts_seal_premises.sql, 20261004120000_lms_presets_espelho_sub_presets_e_frente_ceres.sql): in sync / igual ao código.

Version history / Histórico de versões

Worked examples (computed by the code) / Exemplos calculados pelo código

SAO Matrices

Environment, Safety & Health (ESH) risk assessment using Systematic Assessment of Operations matrices.

• Multi-scenario evaluation — Assess risks across environmental, occupational safety, and operational health domains simultaneously.
• Parameter-based risk scoring — Observations feed directly into matrix calculations for evidence-based risk levels.
• Unit-aware calculations — Automatic unit conversion ensures consistent risk scoring regardless of input units.
• 9 parameter definition files covering environmental, safety, and health indicators.

Compliance Validation

Multi-level compliance validation against environmental regulatory standards.

Built-in Regulations

• CONAMA 420/2009 — Brazilian soil and groundwater quality standards (VR, VP, VI thresholds).
• CETESB DD-256/2016 — São Paulo state reference cleanup values.
• NR-15 — Occupational exposure limits.

Domain Validator Engine

A generic, extensible validation engine that loads domain-specific rules from JSON templates:

• 3-level validation: observation → element → site.
• Thresholds keyed by CAS Number for unambiguous substance identification.
• Custom domain templates can be imported from docs/templates/ (e.g., EPA GAC, GHG-BR).
• Validation results feed the EIS Cs (Consistency) and Cm (Compliance) axes.

Compliance Presets

A compliance preset bundles, under one id and version, the regulatory basis of a model: authority and jurisdiction, legal basis, effective dates, validation profile, GHG factors (GWP version and horizon), emission factor registry, EIS weights, risk targets, coordinate system, units, currency, language and audit retention.

Activating a preset records its id, version and contentHash. The EIS and the seal only use it while the stored preset still has that hash and is not revoked; otherwise the calculation is blocked instead of silently changing. The CETESB risk preset carries the risk targets (ILCR 1e-5, HQ 1, engine CETESB v4.01); the worldwide Pareto envelope uses the strictest target (1e-6).

Presets are also the sub-presets of the ECBYTS Seal fronts. The catalog below, with versions, hashes and the version history, is generated from the code; a version or content change shows up here on the next generation.

Canonical catalog (generated) / Catálogo canônico (gerado do código)

• Boot default (violations panel) / padrão do boot: global-pareto-most-restrictive-worldwide. Random model default / padrão do modelo random: br-sp-cetesb-dd256-2016.
• componentsHash = SHA-256 of the canonical components JSON (buildComponentsHashInput). Definition hash = SHA-256 of the whole preset body except contentHash.

EIS weight presets / Presets de pesos do EIS

Model presets / Presets de modelo

Version history / Histórico de versões

Validation Profiles

Pluggable compliance rule engine for domain-specific validation beyond the built-in CONAMA/CETESB rules.

• JSON-based profiles — Define compliance rules in portable JSON format (CETESB DD-256, CONAMA 420, EPA GAC, custom).
• Rule types — Threshold checks, required field validation, unit verification, and statistical outlier detection.
• Batch validation — Validate all observations at once with results exportable as CSV. Errors include the one-based row position in the validated batch and the field when the rule targets a field. This position is not necessarily the original spreadsheet row.
• Missing values — Empty analytical values remain missing, not zero. A required-field rule reports empty values while preserving a measured zero.
• Unsupported rules — Unknown rule types stop validation with an explicit error; they are not silently accepted. Correct the profile before running it again.
• Error recovery — A failed new run invalidates the previous report. Correct the data or profile and run validation again. When source location is supplied by the import, CSV includes source file, sheet and row separately from the batch position; missing source location is left blank.
• Domain rules — The existing Domain Validator supports allowed values and numeric limits. Required fields reject whitespace-only text; allowed-value rules also check zero and false. Numeric checks reject non-finite values, booleans and containers rather than coercing them into measurements.
• Record balance — Every run reports summary.records: total = clean + flagged, how many flagged records are blocking (prevention/intervention/critical) and an unevaluated list with the reason per row. A non-numeric value such as abc is reported as a value_parse finding instead of being skipped.
• Censored values — <0.5, ND, >10 are parsed as censored results and evaluated at the reporting limit with a censored flag; the censored_value rule type reports them explicitly. Decimal comma is accepted.
• Duplicates — The duplicate_check rule type flags records sharing a key (default elementId+parameterId+date, configurable via fields). Duplicates are reported, never removed automatically.
• Sender report — The results panel and the CSV list, per finding: batch row, source file / sheet / row when the import supplies them (accepted as sourceLocation, source or flat sourceFile/sourceSheet/sourceRow), field, rule, message and a suggested fix. Each finding carries a stable fingerprint; re-running the same profile classifies findings as resolved, persisting or new, and resolved findings are kept in the CSV so a resubmission can be traced.
• Human decision — No finding is discarded silently. Each one can receive a recorded decision (accept, reject, correct, defer) with a mandatory reason and optional reviewer; decisions persist with the profiles and are exported in the CSV. The panel shows how many findings still have no decision.
• Field comparison and templates — Custom domain rules can compare a field with another field of the same record (compareField, e.g. screen top < screen bottom); unknown operators are rejected at definition time. The Domain Editor exports a CSV template per entity with a hint row and a _template_version column (domainId@version); Test Data checks that submitted records declare the matching template version.
• Logical entities — Domain entities extend the data model as a governed logical contract. The Data Studio schema panel lists them under “Logical entities” next to the physical SQLite tables; they are not SQL tables and no physical table is created by saving a domain.
• Import community-contributed profiles from docs/templates/ or create your own.

ENV-05 — EDD submission portal

Receive EDD packages from external senders with a deterministic protocol, a visible state, an error report for the sender and a resume path that never duplicates a package.

• Audience — external senders (laboratories, consultancies) who deliver EDD packages, and the internal team that follows each protocol (RF-05).
• Prerequisites — none. The portal opens from the More menu (EDD submission portal); the guided tour EDD submission portal fills in a synthetic sender and a 3-line CSV package.
• Steps — fill in sender and organisation, choose the package and press Send EDD. The portal hashes the package (SHA-256) and issues a protocol EDD-YYYYMMDD-HHMMSS-… that is deterministic for package, sender and instant. To resume after a correction, type the previous protocol in Previous protocol and send the corrected package. To follow a protocol, use Look up protocol.
• Synthetic example — edd-sintetico-tour.csv has PM-02 with an empty value. Sending it again without a previous protocol is refused with the message this package was already received under protocol …; sending the corrected file (PM-02 = 1.2) with the previous protocol produces Attempt: 2 (resumes …).
• Result — every record (protocol, sender, package hash, attempt, state, optional validation snapshot and resubmission delta) lives in the model and travels with the .ecbt key. The history table lists all protocols, newest first.
• Errors — empty sender or missing package: no protocol is issued. Identical package: refused, the existing protocol is named. Previous protocol unknown, already validated, or from another sender: the resume is refused with the reason.
• Limits — no backend and no e-mail: the protocol is proof inside this model, not a notification. The state becomes validated/rejected only when a validation-profile result (ENV-13/14) is attached at send time (opt-in checkbox).
• Related — ENV-13 Pre-validation, ENV-14 Sender Report, ENV-06 Versions & Signature. Video: pending for this chapter.

ENV-06 — Immutable versions and ECDSA signature

Freeze a version of a result with a SHA-256 content hash, chain it to the previous version and sign it with an ECDSA P-256 key, so that any later change of a single byte is detected as tampering. This is layer 1 of the signature decision: it does not replace ICP-Brasil or gov.br.

• Audience — the technical lead who closes a version of a result and must later prove nobody changed it; auditors who verify offline (RF-06, layer 1).
• Prerequisites — a browser with WebCrypto and IndexedDB (the local key vault). No certificate is needed for layer 1; the panel creates an ECDSA P-256 key if none exists.
• Steps — open ECBT Score › How I reached this result and scroll to Versions and signatures. Press Sign new version: the current audit-trail result becomes v1 (number, canonical-content SHA-256, timestamp, previous hash or GENESIS, version hash, ECDSA signature with the public key embedded). Press Verify versions: hashes, signature and chain are recomputed. Guided tour: Immutable versions and ECDSA signature.
• Synthetic example — Simulate tampering (1 byte) appends one character to the presented content and verifies again: the content hash no longer matches and the verdict is TAMPERED. The signed record itself is frozen and unchanged — that is what makes the difference provable.
• Result — three verdicts, never collapsed: valid, tampered (hash or signature disagrees) and unavailable (the key could not be read — not evidence of fraud). The chain check confirms contiguous numbering, links to the previous version and non-regressing timestamps.
• Errors — if the vault is unavailable the panel says so and signs nothing. A signature that was not checked is shown as unverified, never as valid.
• Limits — versions signed here live in the session (not yet persisted in the .ecbt key or Supabase). Layer 1 is ecbyts' own signature: it does not replace an ICP-Brasil certificate (PAdES, layer 3) nor the gov.br signer (layer 2); both depend on the responsible person's credentials, run server-side and are not available yet.
• Related — Blockchain Integrity, ENV-05 Submission Portal, EIS Score. Video: pending for this chapter.

ENV-04 — EDD designer and spreadsheet formats

Design a versioned schema for electronic data deliverables: entities, fields, mandatory fields, allowed values, numeric limits and field-to-field comparison; hand the sender a CSV template bound to the schema version and check that version on the received records.

• Audience — schema authors (data managers) who publish the EDD format that laboratories and consultancies must follow (RF-04 of the environmental data workflows).
• Prerequisites — none. Without a saved domain the guided tour opens an unsaved New Domain draft; nothing is persisted until Save.
• Steps — open Analyze > Domain Validators; pick a domain or press + New Domain; add rules per entity (Required, One Of, Numeric, Pattern, Custom); in a Custom rule fill either a constant value or the compare field input to compare two fields of the same record; press Template CSV to download the entity template; open Test Data, paste received records and press Run Test. Guided tour: EDD designer: schema, template and version (category Environmental Workflows).
• Synthetic example — domain well-edd version 3.2, entity WELL with well_id required, status one of active | sealed, and the Custom rule screen_top lt screen_bottom. The template is template-well-edd-WELL-v3.2.csv: header well_id, status, screen_top, screen_bottom, _template_version, a hint row and a sample row carrying well-edd@3.2.
• Result — records that declare _template_version are checked against <domainId>@<version>: the Test Data panel reports Template version well-edd@3.2 confirmed for all records, or lists each mismatching row with the value it carried (for example a sender still using well-edd@3.1).
• Errors — a Custom rule without value or compare field, a compare field equal to the field itself, or an unknown operator is a definition error and the run stops; comparing a number with text fails instead of passing as NaN; a compared field that is empty in the record is reported as a warning, never skipped.
• Limits — the template covers one entity per file (the active tab); the version check only runs when the records carry the _template_version column. Publishing means saving the domain in this browser profile and exporting its JSON; there is no server-side registry of published schemas yet.
• Related — Validation Profiles, ENV-12 Logical Entities, ENV-13 Pre-validation, Data Ingestion. Video: pending for this chapter.

ENV-12 — Model extension by logical entities

Extend the data model through governed logical entities declared by domain validators and browse them in the Data Studio Schema panel next to the physical tables. A logical entity is a versioned contract, not a SQL table.

• Audience — administrators who extend the model with new entities or fields under a governed contract (RF-12).
• Prerequisites — at least one domain saved in Domain Validators (see ENV-04); the Data Studio SQL mirror loaded (it loads with the current model).
• Steps — open Data Studio (Processing module); in the left Schema panel read Tables (physical SQL tables of the in-browser mirror) and then Logical entities (domain validators); expand an entity to see its fields. Guided tour: Logical entities in the Schema panel.
• Synthetic example — the saved domain well-edd v3.2 shows as WELL · Well EDD v3.2 (logical) with the fields well_id, status, screen_top, screen_bottom: the union of the fields referenced by rules, compared fields and unique-key fields.
• Result — the entity and its fields are browsable as a contract; each field's tooltip reads logical field (no SQL column). Adding a field or entity is done by editing the domain and publishing a new version; the panel, the CSV template and Test Data reflect it immediately. The saved domains travel inside the exported .ecbt key (section logicalDomains) and are restored on import: a key without the section leaves local domains untouched, and a key that carries one replaces the domain of the same id.
• Errors — a domain whose definition is invalid does not save, so it never reaches the panel; the section is absent when no domain is saved (the guided tour shows that step as unavailable by design). When the model has access control configured, a user without the admin (or owner) role cannot add, change or delete an entity or field: the Domain Validators editor opens read-only with a visible notice, the save is refused with logical-extension-forbidden, and a key opened by that user does not extend the local model.
• Limits — by decision, no physical table is created for a logical entity: no DDL runs, SQL queries cannot select from it and permissions follow the model's own role-based access (extension requires the admin role). The logical extension is never written to the cloud model record (models.model_data), which a public model would expose; it travels only in the key the administrator exports on purpose. The physical tables listed under Tables are created by the app, not by administrators.
• Related — ENV-04 EDD Designer, Data Studio, Validation Profiles, Import / Export. The Portuguese guide video is recorded from the guided tour on the synthetic domain; pause or replay for reading.

ENV-13 — Pre-validation before promotion

Apply the exact schema rules to a received batch before it is promoted, and read a record balance that always closes: total = clean + flagged, with unevaluated rows explained.

• Audience — data managers and reviewers who receive laboratory or field batches (RF-13 of the environmental data workflows).
• Prerequisites — observations loaded in the model (import wizard, data entry matrix or a random demo model) and at least one validation profile: built-in CETESB DD-256 / CONAMA 420 or your own JSON.
• Steps — open Analyze > Validation Profiles; pick the rule set; press Run on that row (or select several and press Run Active); read the Last run panel. Guided tour: Pre-validation before promotion (category Environmental Workflows).
• Synthetic example — two observations from lab-2026-03.xlsx, sheet Results: row 42 with a censored value <0.5 and row 43 with an empty value. A profile with required_field on value and censored_value flags both rows (row 42 censored, row 43 missing value) and the balance line closes: total = clean + flagged, 0 blocking, 0 unevaluated.
• Result — the balance line reports total, clean, flagged and blocking counts and lists unevaluated rows with the reason. A non-numeric value such as abc becomes a value_parse finding, never a skipped row.
• Errors — an unknown rule type stops the run with Unsupported validation rule and invalidates the previous report; there are no stale results. With no observations the run reports zero records and a warning toast.
• Limits — the batch row is the position in the validated set, not the spreadsheet row (see ENV-14 for source locations). Validation runs on the model already loaded; it does not gate the import wizard itself.
• Related — Validation Profiles, ENV-14 Sender Report, ENV-15 Post-import QA/QC, Data Ingestion. Video: pending for this chapter.

ENV-14 — Error report for the sender

Return errors to the sender by file, sheet, row and field, with rule, message and suggested fix, and prove on resubmission which earlier errors were resolved.

• Audience — whoever returns a rejected batch to the laboratory or consultancy and later checks the corrected resubmission (RF-14).
• Prerequisites — a completed validation run (ENV-13). Source locations appear when the import attached sourceLocation (file, sheet, row) to each record; the ingestion pipeline does this for spreadsheet imports.
• Steps — open Validation Profiles; read the Last run table (Row, Source, Field, Rule, Severity, Message, Suggested fix, Decision); press Export CSV; send the file; after the corrected batch arrives, run the same profile again. Guided tour: Error report for the sender.
• Synthetic example — row 43 of lab-2026-03.xlsx / Results has an empty value; the finding shows Fill in "value" as suggested fix. After the sender fills the value and the profile runs again, the balance line reports 1 resolved.
• Result — CSV columns include profile version, batch row, source file / sheet / row, field, rule, message, raw value, censoring, suggested fix, a stable fingerprint, resubmissionStatus (new, persisting, resolved) and the recorded decision. Resolved findings stay in the file so the correction is traceable.
• Errors — Export CSV with no findings shows No validation results to export. A missing source location is left blank, never guessed.
• Limits — the panel lists up to 200 findings; the CSV always carries the full report. Resubmission status compares against the previous run of the same profile in this session.
• Related — ENV-13 Pre-validation, ENV-15 Post-import QA/QC, Data Ingestion. Video: pending for this chapter.

ENV-15 — Post-import QA/QC

Configure quality flags for censored values, duplicates, units and outliers, and record a human decision with a reason for every finding. No data is discarded silently.

• Audience — quality reviewers who accept, reject, correct or defer each finding after an import (RF-15).
• Prerequisites — a validation run whose profile includes quality rules: censored_value, duplicate_check (key defaults to element + parameter + date, configurable via fields), unit and threshold rules, statistical outliers.
• Steps — open Validation Profiles; in the Last run table press Decide on a finding; choose accept, reject, correct or defer; type the mandatory reason; the row shows the decision and the balance line updates the pending count. Guided tour: Post-import QA/QC decisions.
• Synthetic example — <0.5 is parsed as censored (lt) and evaluated at 0.5 with a censored flag; the reviewer records correct: Lab resent value for row 43 with reviewer e2e-reviewer. The balance line then reads 1 recorded.
• Result — decisions persist with the profiles, travel in the CSV (decision, reason, reviewer, timestamp) and in the .ecbt key under validationProfiles.decisions. Pressing Revise records a new decision without erasing the trail.
• Errors — a decision without a reason is refused (Decision not recorded). Duplicates are reported, never removed automatically.
• Limits — the Decide button exists only when there are findings; with a clean batch the guided tour shows that step as unavailable by design. Outlier and unit rules depend on the profile in use.
• Related — ENV-13 Pre-validation, ENV-14 Sender Report, Validation Profiles, Import / Export. Video: pending for this chapter.

Constants Manager

User-defined constants for scientific calculations: emission factors, uncertainty values, unit conversion factors, and site-specific parameters.

• Constants are referenced by the Calculator engine for metric computations.
• Editable via the Constants Modal (Optimize tab).
• Persisted in the model and included in ECBT exports.

Guided Workflows

Step-by-step guided workflows help users through standard environmental engineering processes.

• Workflows are defined declaratively and executed by the workflow engine.
• Each step can collect data, validate inputs, and call platform actions.
• Workflow events integrate with the EventBus for real-time progress tracking.
• Access via Analyze > Workflows.

Spatial Blueprint (DXF)

Import CAD site plans as Spatial Blueprint elements using the DXF ingestion pipeline.

• Supports DXF files from AutoCAD, QGIS, and other CAD/GIS tools.
• Parses layers, polylines, circles, text, and blocks.
• Creates a blueprint family element with the imported geometry rendered in the 3D viewport.
• Use File > Import DXF to start the import process.

Data Ingestion

Bulk import environmental data from spreadsheets and documents.

Spreadsheet Import (EDD)

• Import XLSX and CSV files with the bulk import wizard.
• Map columns to element properties, parameters, and campaign dates.
• Supports Electronic Data Deliverables (EDD) format from laboratories.

Rich Document Ingestion (v0.2)

• Extract data from PDF and DOCX reports using neuro-symbolic processing.
• PDF extraction via pdfplumber server-side for high-fidelity table parsing.
• Split-view interface: source document on the left, extracted data on the right with source grounding highlights.
• Automatically identifies tables, measurements, and structured data.
• Includes a Cost Framework L1 for extracting financial data from environmental reports.
• AI-powered analyzer with decision tracking for audit trails.

Data Entry Matrix

Bulk data entry interface for observations, designed for rapid field data input without navigating between modals.

• Spreadsheet-like grid — Tabular interface for entering multiple observations at once. Select elements as rows, parameters as columns.
• Parameter and unit selection — Configure which parameters appear per column with automatic unit defaults.
• Accessible from the Constellation HUD (bottom panel) — Data Entry tab.
• Values are validated in real-time against compliance thresholds (highlighted in red when exceeding limits).

Storyboard & Sequencer

Create animated sequences and video presentations from your environmental model.

• Timeline Sequencer — Arrange scene snapshots and camera transitions on a timeline.
• Cluster Animations — Group related elements for coordinated visual storytelling.
• Playback — Preview animations directly in the 3D viewport.
• Plume Animation — Animate contamination plume evolution over time.
• Veo 2 Video Generation — Generate photorealistic environmental videos from scene descriptions using Google Veo 2. Deterministic seeding ensures reproducible outputs.
• Keyframe Validation — Automated consistency checks between keyframes: camera path smoothness, element visibility continuity, and temporal coherence.
• Scene Seeding — Deterministic random seeds for reproducible camera paths and animation sequences across exports.

Pipelines (BPMN)

Automate multi-step workflows using a BPMN-inspired pipeline system.

• Define pipelines as sequences of platform actions with conditional branching.
• A Pipeline Editor UI for visual pipeline design.
• Pipeline executor runs registered actions with a security allowlist (~15 safe action names).
• Pipeline events integrate with the EventBus for status tracking.
• Treatment system integration — Treatment System elements can link to operational pipelines. Run, monitor, and track execution from the element inspector.

Treatment Systems

Model and track remediation and treatment infrastructure linked to operational pipelines. The treatment_system family connects physical treatment equipment to automated workflows and cost accounting.

• System types — Pump & Treat, SVE (Soil Vapor Extraction), Air Sparging, PRB (Permeable Reactive Barrier), MNA (Monitored Natural Attenuation), ISCO, bioremediation, oil-water separators, septic systems, and custom configurations.
• Operational parameters — Track flow rates, extraction volumes, treatment efficiency, energy consumption, and maintenance schedules as observations.
• Pipeline integration — Link treatment system elements to BPMN pipelines for automated monitoring, alerting, and reporting. Run pipelines from the element inspector.
• Cost tracking — CAPEX + OPEX rollup per system with L1–L4 cost aggregation feeding the governance module.
• Compliance targets — Define target concentrations and track progress toward CMA (Concentração Máxima Aceitável) goals over time.

Well Geology

Advanced geological analysis modules for monitoring wells, based on Brazilian and international stratigraphic standards.

• Geological cross-section — SVG cross-section correlating lithologic layers across wells with ABGE-standard patterns and colors.
• Stratigraphy engine — Normalizes raw lithologic data into ISO 14688 / AGS4 compatible schema with SUCS classification.
• Well compliance checker — Validates wells against NBR 15495-1:2007 (ABNT standard). Scores: ≥80 = ok, 50–79 = warning, <50 = error.
• Constructive profile — SVG well construction diagram showing casing, screen, grout, and filter pack.

Wells: lithology and construction intervals (env-08)

Goal: record the lithologic layers and the construction elements (casing, screen, filter pack, grout) of a monitoring well so that the graphic profile and the interval table always reconcile, and so that invalid intervals are detected before anything is saved. Audience: field professionals who register boreholes and internal technical reviewers. Prerequisites: a model with at least one well element; the guided tour Well lithology and construction intervals creates a synthetic well when the model has none.

Steps. Select the well in the element list and open its Well Profile module (family modules menu). The left side draws the constructive profile and the lithologic log; the Edit button opens the interval editor with one row per layer (top, base, soil type, description, SUCS, consistency) and one row per construction element (top, base, type). Change a depth and press Save: the module validates every interval before persisting. Errors block the save and are listed above the table (role="alert"), each pointing to its row, which is outlined and marked aria-invalid. Warnings (a gap between two layers) are listed but do not block.

Detected errors. INVERTED (top at or below the base), NEGATIVE, NON_FINITE, EXCEEDS_DEPTH (layer beyond the well depth, or construction element beyond the drilling depth), OVERLAP between consecutive lithologic layers and TOTAL_EXCEEDS_DRILLING. The rule set is the same one the renderer uses, so every row that the drawing would silently drop is now reported instead of disappearing.

Result. After the correction the error list disappears, the profile is saved on the element (data.profile) and the SVG draws exactly one lithologic rectangle per table row — the reconciliation the acceptance criterion asks for. Limits: depths are metres below the wellhead; the topographic elevation toggle requires the element to carry an elevation. Related: Well Geology, Water-level series, Guided Tours. Video demonstration: pending (not yet recorded).

Water-level series with explicit datum (env-09)

Goal: store water-level measurements with an explicit datum, unit and date, compare campaigns and export the series without losing the raw value or its origin. Audience: hydrogeologists and technical reviewers. Prerequisites: a well with at least two water_level observations that declare a datum (msl, or depth_below_reference together with a reference elevation on the observation or on the well). Observations without a datum are excluded from every curve and listed as datum_missing issues — they are never silently assumed to be elevations.

Steps. Open the Report editor and click ecbyts figures. The selector lists a Hydrograph (water level per well) entry for every well with two or more valid readings, plus an all wells candidate. Tick the candidates you want and press Insert selected: each becomes a corporate-layout figure in the report. The curve is drawn in metres above mean sea level; the footer states the datum declared by the observations and how many readings were converted, and how many were excluded.

Export. Open the command palette (Ctrl+K) and run Export water-level series (TSV). The file keeps, per reading, the well, date, campaign, raw value and raw unit, datum, reference elevation, the conversion note, the head in metres and the quality flags — values and origin are preserved, nothing is rounded away. The same series feeds the water-table layer of the Interpolation panel, so the map and the table agree.

Errors and limits. A reading without a parseable date, a depth reading without a reference elevation, or a unit that cannot be converted to metres is reported as an issue and never enters the curve. Comparison between campaigns is well-by-well (head difference in metres). Related: Potentiometric Maps, Reports, Wells. Video demonstration: pending (not yet recorded).

Human-health risk assessment record (env-10)

Goal: store a risk scenario (substance, exposure scenario, receptor, pathways, concentrations, method) as a record with provenance, and keep the record distinct from the calculation: a number is attached only when the method is implemented and validated, and regulatory approval is never presumed. Audience: consultants and internal reviewers. Prerequisites: none — the panel works on a synthetic scenario.

Steps. Open Risk Assessment (Analyse menu, command palette or Alt+R). Choose the substance and the exposure scenario, type at least one concentration and press Calculate CMA. The panel first stores the scenario as a record; the engine result (incremental cancer risk, hazard quotient, acceptable concentration, limiting pathway) is attached to that record together with its provenance: receptor and age group, pathways, media, method identifier, whether the method is implemented and which validation suite covers it, a digest of the input, and the timestamp. The line Regulatory approval: not asserted is part of the record.

Result. Records persist inside the model (model.riskAssessment) and travel with the .ecbt key. Closing and reopening the panel — or reloading the model — shows the last record with the note restored from the saved model, not recomputed; the digest proves which input produced the number. Limits: when the method is not implemented for the chosen scenario the record is stored without a result and says so; nothing in the panel claims regulatory acceptance. Related: SAO Matrices, Compliance Validation, Guided Workflows. Video demonstration: pending (not yet recorded).

ENV-02 — Internal and external profiles: roles per organization

Roles are resolved per organization and fail closed: membership in one organization grants nothing in another, the UI only mirrors the canonical policy, and the backend (row-level security) is what refuses an action outside your scope — with the error shown, never swallowed.

• Audience — organization administrators (internal reviewers) who configure governance, analysts who only read it, and external senders who must never see or change another organization's scope (RF-02).
• Prerequisites — an authenticated session with an active organization. Without one the panel does not open (authenticated_organization_required) and the guided tour shows its first step as unavailable instead of pretending success.
• Steps — open Data Studio > Communicate > Governance and Pilot. The panel resolves your role in this organization through the canonical policy (canCurrent(MANAGE_MEMBERS)): admin or owner can save, member and guest read. Try to register an approval outside your scope: the database refuses it (RLS, error 42501) and the alert above the sections reads operation denied by the backend. Guided tour: Roles per organization.
• Synthetic example — two organizations and three roles. Org A: reviewer admin, analyst member; Org B: the same people have no membership; an external sender is guest in Org A only. Read/write/share evaluated by evaluateScopedAccess gives 7 grants and 11 denials; every cell outside the person's organization is outside_org_scope. The screenshots come from the analyst (member) session against a backend that answers 42501.
• Result — the read-only note and disabled Save buttons mirror the role; the denied write shows the backend message in a role="alert" box and nothing is saved. Pilot flags stay OFF unless window, published SHA and distinct people are all present, and only for that tenant.
• Errors — 42501 / RLS: role does not authorize the change; 23514: record fails the table check constraint; 23503: reference to a missing account or organization. Each one is displayed, never thrown away.
• Limits — the institutional role (stakeholder) never grants access; only the organization role does. The two-organization matrix is proven in unit tests and, in the browser, against a stubbed backend: creating real accounts in two organizations is outside this chapter.
• Related — ENV-11 Audit Trail, Data Ingestion, Guided Workflows. Video: pending for this chapter.

ENV-03 — Corporate authentication: OIDC, mapping, provisioning and revocation

Sign in with your organization's corporate account over OIDC: the identity provider authenticates, the e-mail domain selects the organization, the IdP group selects the role and provisioning is fail-closed — without proof of mapping there is no corporate session; a revoked identity loses its memberships and sessions.

• Audience — organization administrators who connect their identity provider, and corporate users who sign in with the account the organization already manages (RF-03).
• Prerequisites — an OIDC identity provider registered in the authentication layer (provider keycloak; the test IdP is a local Keycloak realm, by owner decision) and one mapping rule per issuer in corporate_idp_rules: accepted e-mail domains, target organization, default role (guest or member) and the optional IdP-group → role map. Migration 20260909230000_corporate_idp_provisioning.sql is versioned and proven locally; applying it to a hosted project is the owner's act.
• Steps — open Login; press Sign in with a corporate account; authenticate at the provider; on return the application calls corporate_provision_identity() with your session and reads the answer. Admitted: the user menu shows Corporate account (OIDC) · role. Refused: the session is closed, the modal reopens and the reason is shown above the list Why can a corporate sign-in be refused? (the list is rendered from the provisioning contract, not typed by hand). Guided tour: Corporate account (OIDC): sign-in, mapping and revocation.
• Synthetic example — realm ecbyts with users analyst@example.test (no group), reviewer@example.test (group ecbyts-admins) and outsider@other.test; rule: issuer …/realms/ecbyts, domain example.test, default member, ecbyts-admins → admin. Measured against the real local IdP: analyst → create_membership as member, second sign-in noop; reviewer → admin (groups arrive in identity_data.custom_claims); outsider → email_domain_not_allowed; after revocation by the service role the old token gets 403 and the refresh token 400.
• Result — a stable external identity (issuer|subject) bound to one organization and one role; the membership is created on first sign-in, updated when the group mapping changes, untouched otherwise; an existing owner is never downgraded by directory sync.
• Errors — issuer_not_trusted, email_domain_not_allowed, email_not_verified, invalid_claims, group_mapping_escalation_blocked, organization_missing, identity_revoked and, when the provisioning function is unreachable or answers something malformed, provisioning_unavailable / provisioning_rejected. Every one closes the session and is displayed; none is swallowed. On token refresh, an identity that is no longer active ends the session with identity_inactive.
• Limits — one OIDC provider (SAML is deferred until a corporate customer requires it); the button is not labelled “SSO” until the receipt against the real IdP is accepted by the owner; a corporate session still passes the existing invite, terms and registration gates; the screenshots come from the product UI against a simulated identity provider, and the measured flows above come from the local Keycloak runbook (npm run env03:keycloak).
• Related — Authentication, Corporate SSO status, ENV-02 Roles per Organization, ENV-11 Audit Trail. Video: recorded from the guided tour (see the media manifest for this chapter).

ENV-11 — Database audit: actor, operation, object, previous and new version

Every versioned change is recorded with actor, operation, object and the previous and new version when applicable; the history of one object is correlated change by change, and the trail cannot be edited or deleted by anyone — in the client by contract and in the database by migration.

• Audience — internal reviewers and auditors who need to know who changed what, and when, without being able to rewrite the record (RF-11).
• Prerequisites — none. The panel reads the session trail; with no entries it shows zero entries and the access matrix. It never invents data.
• Steps — open More > Audit trail (also in the system catalog). Section 1 lists entries: create carries only the new version, delete only the previous, update/transfer both. Section 2 correlates the history of one object and checks continuity: the previous version of each change must equal the new version of the change before it. Section 3 shows who can do what. Guided tour: Audit trail.
• Synthetic example — well W-01: Ana (reviewer) creates it with depth 12; Bruno (analyst) updates 12 → 15 (linked); Carla records an update whose previous version says 14 — the history flags before_differs_from_previous_after at that sequence and marks the object inconsistent. A fourth entry deletes sample S-7 with its previous version only.
• Result — every entry hashes the previous one; the header verifies the chain. The access matrix shows read_own for guests, append from member, read_all from admin, and update/delete refused for every role (audit_immutable). In the database, migration 20260905230000_audit_log_drop_update_delete.sql dropped the UPDATE and DELETE policies of public.audit_log; SELECT and INSERT remain.
• Errors — a versioned change without actor, object or the required version is refused before writing (audit_actor_required, audit_before_version_required, …). A rewritten or truncated trail fails assertAppendOnlyExtension.
• Limits — this panel shows the client-side trail of the current session; the database trail is queried through the audit views with role-limited SELECT. Migration 20260905230000_audit_log_drop_update_delete.sql is already applied to the production database (2026-09-05): public.audit_log keeps only its SELECT and INSERT policies, so no role — not even owner — can rewrite or erase a row through the API.
• Related — ENV-02 Roles per Organization, Blockchain Integrity, Data Audit. Video: pending for this chapter.

ENV-01 — Areas and geometries with explicit CRS

Import shapefile or KML geometries as areas, wells and drainage lines with the coordinate reference system stated up front: the wizard shows the CRS status, blocks import without a .prj and accepts an explicit declaration; KML enters as CRS84 by standard.

Guided environmental data presentation

Open the guided presentation to follow the demonstration course in the application. To open a specific block, keep training=demo-cetesb-gac and modo=apresentacao and add its lesson identifier. For example, open the QA/QC block. Use the block link to return directly to that part of the presentation after an interruption.

• Audience — data managers who receive site boundaries, wells and drainage lines from field teams or consultancies as shapefile or KML (RF-01 of the environmental data workflows).
• Prerequisites — a .zip with .shp, .shx, .dbf and, ideally, .prj; or a .kml (OGC KML 2.2). Reading shapefiles needs the shpjs library loaded from its CDN. The file CRS and the model origin are separate: KML requires an explicitly configured, valid and compatible model origin even though its source CRS84 is known. Do not change the model or origin while the file is being prepared or imported.
• Steps — open Home > Import and choose the Spatial route (or use the legacy form Import > Spatial); select the file. For shapefiles the wizard opens with feature count, geometry types, attribute fields, geographic preview and the CRS block; pick the target family and name field and press Import. Guided tour: Areas and geometries with explicit CRS (category Environmental Workflows).
• Synthetic example — the tour builds two in-memory shapefiles with three points (PM-DEMO-01..03, WGS84 longitude/latitude): one without .prj, whose CRS block is red and whose Import button stays disabled until the EPSG:4326 declaration is ticked; and one with .prj, whose block reads GCS_WGS_1984 in green. A KML with a Point, a LineString, a Polygon and a MultiGeometry of two polygons becomes 5 elements (1 well, 1 river, 3 boundaries) with CRS84 recorded in the report.
• Result — every imported element carries data.provenance with format, source file, CRS, CRS source (prj, declared or standard), geometry hash and import date. The import report lists records received, added, duplicates and errors.
• Errors — a shapefile without .prj and without declaration is rejected with CRS missing; only EPSG:4326 can be declared in this version. A KML without any Placemark, with unparseable coordinates, or without a compatible model origin is rejected before geometry insertion. A change of model, origin or edit permission during import rejects stale work. If a partial batch cannot be safely cleaned up, follow the explicit pending recovery guidance; do not assume that every failure removed every record.
• Limits — no reprojection: UTM or other projected coordinates require the .prj and are converted by the geographic origin of the model. Import runs on the whole file; partial selection is not supported.
• Related — ENV-22 Lines, polygons and batches, Data Ingestion, Import / Export, Spatial Blueprint. The Portuguese guide video uses synthetic data; the wizard preview is unavailable in this recording. Pause or replay for reading.

ENV-22 — Lines, polygons and historical batches

Persist lines and polygons and migrate historical batches with reconciliation by stable id and provenance: the report closes counts (received, added, duplicates, errors), reimporting never duplicates, and a failed batch is rolled back proportionally.

• Audience — whoever migrates historical campaigns and geometries into the model and must prove counts, hashes and the absence of duplicates (RF-22).
• Prerequisites — a spatial file (shapefile, GeoJSON or KML) whose features may be points, lines, polygons or multi-geometries. KML declares the source CRS84, but an explicitly configured, valid and compatible model origin is also required. Keep the model, origin and edit permission unchanged while importing. The same file can be imported more than once after any pending recovery is resolved.
• Steps — open Import > Spatial, select the file and read the report in the progress overlay; open the left panel to see the new elements; import the same file again and compare the report. Guided tour: Lines, polygons and historical batches.
• Synthetic example — the tour imports tour-env-22-campanha-2019.kml (Point, LineString, Polygon, MultiGeometry with two polygons). In a fresh demonstration batch, the first import receives 5 records, adds 5 and reports 0 duplicates. Reimporting that file receives 5, adds 0 and reports 5 duplicates: the batch still contains five elements, in addition to any preexisting model data. Tour cleanup must be limited to unchanged records created by that tour session; a matching filename does not establish ownership.
• Result — each feature gets a stable id (imp- plus a hash of dataset, layer, position and geometry) and data.provenance with geometry hash and count, so a batch can be checked against its source. Reconciliation mode skip ignores ids that already exist.
• Errors and recovery — failed batches attempt proportional rollback of their own unchanged records. Later edits, foreign child links or a changed model/origin can prevent safe cleanup: the interface keeps an explicit pending recovery instead of forcing deletion or claiming that nothing was imported. Resolve the indicated context or data conflict before retrying. If data were already applied and only finalization is pending, retry finalization without importing again. The tool never restores an external origin automatically.
• Limits — reconciliation compares ids, not attribute values: a feature whose geometry changed gets a new id and is added, the old one is not replaced automatically. Modes replace and suffix exist in the library but the UI uses skip. Pending recovery capabilities belong to the current session; reopening a dialog is not a guarantee of recovery after a browser restart. Model persistence and reconstruction are tested separately from recovery of an unfinished operation.
• Related — ENV-01 Areas and geometries, Data Ingestion, Import / Export. The Portuguese guide video demonstrates synthetic import, duplicate reconciliation and session cleanup. Rollback is explained, not induced in the recording.

ENV-07 — Environmental data entities from an EDD

Import a laboratory EDD package (Location, Sample, TestResults) and see where each entity lives in the model: points become elements, sampling dates become campaigns, and samples with their results become observations on the point.

• Audience — reviewers and data managers receiving laboratory EDD packages (RF-07 of the environmental data workflows).
• Prerequisites — an EDD workbook with Location, Sample and TestResults sheets. The reference fixture is tests/e2e/fixtures/env-edd/lab-edd-package.xlsx (6 points, 22 samples, 126 results; one sample references a point that does not exist).
• Steps — open Data > Import; drop the workbook; read the recognised format and sheet counts; finish the wizard and apply the merge; open the Elements tab (points), the Campaigns tab (sampling dates) and select a point to see its observations. Guided tour: Environmental data entities from an EDD (category Environmental Workflows).
• Relations — Location.sys_loc_code → element; Sample.sys_loc_code + sample_date → campaign; TestResults.sys_sample_code → Sample → observation on the element with parameter, value, unit, matrix, date and detect flag. Each record keeps file / sheet / row for ENV-13/14.
• Result (measured) — the import balance closes: 126 results = 120 observations + 6 discards. The fixture yields 6 elements and 4 campaigns; the six discards are the rows of the orphan sample (code LOCATION_NOT_FOUND, sheet TestResults, row number and a detail naming MW-99), and that point is never created. Measured in tests/e2e/env-c-internal-journey.spec.ts and in the tour walk of tests/e2e/tour-env-07-16-21.spec.ts.
• Limits — the tour does not import the file for you (a file input needs your gesture) and seeds nothing: it shows the panel exactly as your import left it. Twenty-one results keep an unmapped unit and one value is non-numeric; those are kept and reported as issues, not discarded.
• Related — Data Ingestion, ENV-13 Pre-validation, ENV-16 Filter Reconciliation, ENV-18 Integration REST API. Video: pending for this chapter.

ENV-16 — Same selection in map and SQL

Filter observations by parameter and matrix in the interpolation panel and reproduce the exact same selection in Data Studio: the observations table carries parameter, matrix and campaign_id from the same records, so counts must agree.

• Audience — analysts exploring a model by area, campaign and parameter across maps, charts and tables (RF-16).
• Prerequisites — observations with parameterId, sample_matrix and campaignId (an imported EDD or the synthetic model used by the tour test).
• Steps — open Interpolation; choose the matrix and the parameter; press Contamination to generate the plume (the precondition check counts the points that pass the filter); open Data Studio > Processing and run the query the tour writes: SELECT campaign_id, matrix, COUNT(DISTINCT element_id) AS points, COUNT(*) AS results FROM observations WHERE parameter = ... AND matrix = ... GROUP BY campaign_id, matrix. Guided tour: Same selection in map and SQL.
• Contract — the interpolation engine filters o.parameterId, o.sample_matrix and o.campaignId; the SQL table stores the same fields as parameter, matrix and campaign_id. An observation without a campaign is NULL in SQL and never matches a campaign filter on either screen (tests/env-16-datastudio-filter-reconcile.test.mjs).
• Result — for the same parameter, matrix and campaign, the plume point count equals points in the query result.
• Limits — the interpolation panel exposes matrix and parameter; the campaign filter is applied by the engine when a plume is generated for a campaign, and is explicit in SQL. The map uses the latest value per point; SQL counts every observation (results).
• Related — Interpolation, Data Studio, ENV-07 EDD Entities. Video: pending for this chapter.

ENV-17 — Alerts and notifications

Receive submission, error, review and deadline events in the panel and by email. The email channel is real and leaves in a labelled sandbox mode (provider test key); preferences hold on the client and on the server; the same event arrives once; a failure gets a limited retry and a recorded give-up.

• Audience — data managers, reviewers and senders who must be told when a batch is received, rejected, reviewed or due (RF-17).
• Prerequisites — none for the panel (it works offline, in this browser). Email requires a signed-in user with a confirmed address, a saved preference on the server, and the provider test key RESEND_API_KEY_TEST (re_test_*) configured for the create-notification Edge Function — without it the server records the alert in mode No test key and sends nothing.
• Steps — open the Notifications panel (bell in the header, or the guided tour); read an entry; press the preferences button; read the Email channel mode block; per type, enable or disable the alert and tick the channels (In-app, Email); press Save. Guided tour: Alerts and notifications: panel and sandbox email (category Environmental Workflows).
• Synthetic example — the tour creates the panel-only entry Exemplo sintético: lote lab-2026-03.xlsx rejeitado (type processing.import_failed, P2) and deletes it at the end. A P0 alert such as security.alert for user 00000000-0000-4000-8000-000000000001 leaves once as [SANDBOX] [Ecbyts] Alerta: … to the provider sandbox inbox, with the durable idempotency key notification:<sha256>:1.
• Result — the panel lists every entry; the server keeps one notification row per event; the sandbox inbox receives one email per event; the preferences modal labels the last delivery mode: SANDBOX (test key), No test key, Disabled, Failed or No alert left this session, with type, durable state and reason underneath.
• Deduplication — the client outbound gate drops the same event inside a 10-minute window; the server reserves each event durably (notification_dispatch_attempts) so concurrent isolates and page reloads still produce one provider call. Explicit event_id/event_version never reopens; only content-identified reminders may re-emit after their window.
• Deactivation — disabling a type or unticking Email is applied to the local gate (nothing leaves the machine) and saved to notification_preferences; the Edge Function re-reads that row before every send. No row, or a failed read, means no email (fail-closed).
• Errors — a retryable provider failure (408/425/429/5xx, timeout) is retried up to 3 times with the same idempotency key; a permanent one (other 4xx, payload conflict) is not. After the attempts the durable state becomes retryable and, after three server reclaims, uncertain: the give-up is recorded in the receipt and shown as Failed. When the server does not confirm a preference save, a warning toast says so.
• Limits — P0 and P1 entries are never batched in the local panel by design (only P2 social entries merge), so the panel lists each producer call while email and the server row stay single. Push remains a declared stub. Email is sandbox-only until a separate decision authorises a production key; the tour never saves preferences for you.
• Related — ENV-05 Submission Portal, ENV-13 Pre-validation, ENV-14 Sender Report, ENV-02 Internal and external profiles. The Portuguese guide video uses synthetic data and a fake transport injected at the product's transport seam; the sandbox label comes from the real receipt path.

ENV-18 — Integration REST API

The v1 contract is documented and readable; the authenticated write API is deliberately postponed until a real integrator exists. This chapter says what you can call today and what you cannot — the gap is the deliverable, not an omission.

• Audience — teams integrating a spreadsheet or script with a shared model (RF-18).
• What exists — the read/compute endpoint consumed in production by the Excel add-in and three Office Scripts, plus a loopback bridge exposing /api/v1/ecbt for local development. Full reference in API reference; the versioned contract is Integration Contract (v1), and every sentence of it is locked by tests/env-18-api-contract-v1.test.mjs.
• Steps — open Help > API reference in the ribbon (or the API docs card on the Home quick access); read Versioning, Authentication, Transport & CORS and Declared gap. Guided tour: Integration API: contract v1 and its limits (category Environmental Workflows), six steps over the Help menu, the session button, the Save > Shares item and the Home card. The tour never leaves the app nor opens a tab: opening the reference is your gesture.
• External API authentication — the Bearer credential is the access token of a signed-in user. A share code identifies a resource; it never grants identity. The ecbt-api contract requires authentication for POST: missing or invalid identity answers 401, while an unauthorized, expired or revoked share answers 403. GET returns public health information, not model data. Read the external Edge API OpenAPI contract for its operations and response shapes. Inspect ok even on HTTP 200; an application error can use that status.
• Envelopes and errors — /api/v1/ecbt answers {ok, kind, data}. Transport errors carry kind: "error" with HTTP 400 (bad_args), 503 (not_built) or 500; domain errors come back with HTTP 200, ok: false and no kind. Branch on ok, never on kind. Limits: body up to 5 MB (413), JSON only (415), unknown route 404, one pipeline run at a time (409), no pagination on any route.
• What does NOT exist — there is no package creation operation on any surface, so there is no idempotency key to verify; the loopback bridge has no 401/403 of its own; there is no pagination. The contract section Declared gap lists these items one by one.
• Integration scope — the external Edge endpoint exposes shared-model value, table and sum operations. Scientific calculations remain in the client tier under the approved hybrid architecture. Package creation and integration with a specific institutional system require separate contracts. The limits listed above for /api/v1/ecbt describe the local bridge and must not be assumed to apply to the Edge endpoint.
• Related — API reference, ENV-07 Environmental entities, ENV-02 Internal and external profiles, ENV-21 Language and AI assistant. The Portuguese guide video is recorded from the guided tour itself over the real interface; pause or replay for reading.

ENV-19 — SaaS and self-hosted installation

Know in which architecture this app runs and how to install it yourself. The SaaS (static front plus managed Supabase, operated by Ecbyts) and the self-hosted installation (a reproducible script over the Supabase CLI and the build) are assessed separately; the Installation and backend panel shows the architecture declared by the build, the backend host, an on-demand health probe and the installer commands.

• Audience — IT operators and administrators of public bodies or companies that must run the platform on their own infrastructure, and anyone who needs to know whether an instance is the Ecbyts SaaS or a self-hosted installation (RF-19).
• Architectures, assessed separately — SaaS: static front (Vercel/Bluehost) plus managed Supabase, operated by Ecbyts. Self-hosted: the same front and the same migrations/functions installed by scripts/install/self-host.mjs on a local Supabase stack (Docker) or on the customer's own Supabase Cloud project. The panel never infers SaaS from the domain: the build declares INSTALL_KIND (saas, self-host-local, self-host-remote or unknown).
• Prerequisites — Node.js 22 and npm; Supabase CLI; for the local target an active Docker engine (the installer probes docker info --format '{{.ServerVersion}}' and treats an empty answer as stopped); for the Supabase Cloud target SUPABASE_ACCESS_TOKEN, SUPABASE_PROJECT_REF, SUPABASE_URL and SUPABASE_PUBLISHABLE_KEY of the customer project, with the pg_cron and pg_net extensions enabled in its dashboard (migrations require them). The local stack gets both extensions from supabase/roles.sql.
• Steps — open More > Installation and backend to read the architecture, the host and to press Check health. To install: node scripts/install/self-host.mjs --target local prints the plan (dry-run, nothing runs); --apply executes it: supabase start (or supabase link for the remote target), migrations in chronological order (db reset locally, db push remotely), Edge Functions served (locally) or deployed, app/js/supabase-config.js generated for that installation, TypeScript build, and a health probe (auth, REST OpenAPI exposing public.profiles, an authenticated query, and functions/v1/health). On a host where another Supabase stack already uses the default ports, add --project-id <id> --port-base <n>: the installer rewrites supabase/config.toml only during the run and restores it. Guided tour: SaaS or self-hosted: where this app runs.
• Real example — the receipt in docs/reports/ENV_RF19_BCD_20260909.md records the local --apply executed on 2026-09-09 with the isolated project ecbyts-selfhost-rf19 on ports 55320–55329: the steps, their durations, the health probe verdicts and the commands as templates ($SUPABASE_URL, never values). The screenshots of this chapter come from the app built by that run.
• Result — a JSON receipt (.runtime/self-host/receipt-*.json or --receipt) with every step, every command and the health verdicts; exit codes 0 ok, 1 command failed, 2 plan or production guard blocked, 3 health failed. The panel then reports the loopback host with self-host-local declared and the probe online.
• Errors — the installer refuses the Ecbyts production project by ref and by URL (exit 2, zero commands); a blocked plan (missing Docker, CLI or token) never executes; a failing step rolls back proportionally (a stack started by this run is stopped, the previous supabase-config.js is restored byte by byte, background functions are killed); supabase status output is never echoed and secret values never enter the receipt. The CLI's own .env.local loading is disabled (SUPABASE_ENV=test) so the repository production file is never read.
• Update — check out the desired tag and run the same --apply: db push applies only versions missing from supabase_migrations.schema_migrations, function deploy is an upsert by name, the app is rebuilt. Locally, db reset recreates the database, so back up first.
• Backup — node scripts/supabase-backup-local.mjs (structure) and supabase db dump --data-only (data) before every update; Storage objects are backed up from the bucket, not from the database.
• Limits — an isolated localhost does not prove an autonomous installation on a clean machine (the panel says so whenever the host is loopback); Edge Functions require the Supabase Deno runtime; pg_cron and pg_net must exist in the target Postgres; the front build stops at app/ — publish it on your own static host; two migrations share the timestamp 20260804223000 (independent tables, applied in file-name order) and are reported as a warning, not a blocker.
• Related — ENV-02 Internal and external profiles, ENV-18 Integration REST API, ENV-11 Audit trail. The Portuguese guide video walks the panel over the app built by the real local installation; pause or replay for reading.

ENV-21 — Language and AI assistant

Switch the interface between Portuguese, English and Spanish and ask the assistant about the loaded model. The system prompt carries the model context; a provider failure preserves your text.

• Audience — users working in Portuguese, English or Spanish who want contextual help from the assistant (RF-21).
• Prerequisites — a loaded model; an assistant engine (cloud with your key, local OpenAI-compatible endpoint, or in-browser). The tour test uses a mocked local endpoint: no external call.
• Steps — open the language selector in the title bar and pick a language; open the AI Assistant; read the engine badge and token meter; type a question about the model and send. Guided tour: Language and AI assistant.
• Context — every request carries the model context in the system prompt (Elementos no modelo: N, Campanhas cadastradas: M, family summary). The E2E test reads N and M from the page and checks them in the captured payload (tests/e2e/env-21-assistant-context-mock.spec.ts).
• Result — the answer appears in the chat with the engine used; the same panel renders with translated texts in PT, EN and ES.
• Errors — a provider failure (503) shows a recovery notice, keeps your message in the input and leaves the send button enabled.
• Limits — the assistant proposes; the model only changes through explicit user actions. Fourteen other locales fall back to English for the newest strings until translated.
• Related — AI Assistant, Languages, ENV-16 Filter Reconciliation. Video: pending for this chapter.

ENV-20 — Pricing, seals and declarations

Read the billing units, the plans with their limits, the optional services and the seals and declarations in one panel — every price carries the owner's approval state (example or approved). No price, certification or homologation is invented: what has no evidence is stated as absent.

• Audience — whoever evaluates contracting the product (customer, public body, auditor) and needs to know what is charged, what the limits are and what is actually certified (RF-20).
• Prerequisites — none. The panel reads the same tier table the checkout charges from and a versioned approval source; no model, login or fixture is required.
• Steps — open More > Help > Plans, prices and certifications (or the link inside the checkout); read the banner at the top, then sections 1 to 5. Guided tour: Plans, prices and certifications: what is charged and what is proven (category Environmental Workflows).
• Billing units — monthly or yearly subscription, one-time payment, prepaid balance metered per AI token, and per-plan limits (projects, elements, campaigns, storage). The panel also states what is not charged: per hectare, per sampling point or per seat.
• Approval state — the displayed price and the charged price come from mirrored tables; the third leg, the approved source, is a decision of the owner recorded in app/assets/data/price-source.json. While it is pending, the banner says the values are EXAMPLE and every amount carries the badge example — not approved by the owner. Recording the decision switches the same panel to approved by the owner without any code change; changing a price after approval drops it back to example.
• Optional services — library marketplace, courses, invoicing (NFS-e) and the enterprise plan exist in the code but have no approved price table, and the panel says so instead of inventing a value.
• Certifications — the product holds no third-party certification (ISO, SOC 2, INMETRO or similar). Declarations with evidence in the repository (software registration at INPI, LGPD technical controls with pending items) are listed as declarations, not as product certifications, and the list of what is not held is explicit. Self-declared seals are separated from third-party certificates by the anti-greenwashing policy (core/certification/_antiGreenwashPure.ts).
• Receipt — section 5 ties displayed → charged → approved source with the SHA-256 of the canonical price catalog; node scripts/pricing/price-approval.mjs verify reproduces it from the command line.
• Errors — if the approval source cannot be read, the panel still renders every amount as example and shows the reason; it never assumes approval. A source that claims approved without a valid decision key or with an outdated catalog hash is rendered as example with the reason.
• Limits — the panel explains; it does not sell. Amounts shown are examples until the owner records the decision, and this chapter will read approved only after that record exists. Fourteen other locales fall back to English for the newest strings until translated.
• Related — Wallet, ENV-18 Integration REST API, ENV-21 Language and AI. The Portuguese guide video walks the six tour steps over the real panel.

Issues 3D (BCF-like)

3D-anchored non-conformity markers for collaborative issue tracking, inspired by BIM Collaboration Format (BCF).

• Create spatially-anchored issue markers directly in the 3D scene.
• Map-indexed for O(1) lookup performance.
• Persisted to IndexedDB with a sync queue for offline-first operation.
• 3-way merge conflict resolution for multi-user scenarios.

Data Audit

Detect anomalies and potential fraud in environmental datasets.

• Benford's Law Analysis — Check first-digit distribution of observations against the expected Benford distribution. Deviations may indicate fabricated or manipulated data.
• Greenwashing Detection — Flag suspiciously uniform or implausible environmental metrics.

Internationalization (i18n)

16 fully-translated locales with lazy loading, interpolation, pluralization, and RTL support.

• Lazy loading — Only 1–2 JSON files loaded per session for fast startup.
• Interpolation — t('key', { count: n }) for dynamic values in translated strings.
• Pluralization — tp('key', n) via Intl.PluralRules for grammatically correct plural forms.
• Regional formatting — Numbers, dates, and currencies formatted via Intl.* APIs.
• RTL support — Arabic locale triggers dir="rtl" on the root element.
• Switch languages via the titlebar language selector (EN / PT / ES) or any of the 16 locales in settings.

Random Model Generator

One-click demo model generation with realistic environmental data for exploration, training, and presentations.

• 1 boundary with 6 geological strata.
• 3–8 monitoring wells, 1–4 contamination plumes, 1–3 tanks, 1–4 buildings.
• Lakes, rivers, springs, and general markers.
• ESG elements: emission sources, waste streams, effluent points, habitats, individuals, incidents, areas.
• Mining & civil: dams, open-pit excavations.
• Fleet & operations: vehicles, equipment, treatment systems, linear infrastructure.
• Route & flow elements for hydraulic connectivity.
• 3–5 sampling campaigns spanning 2 years with observations per element.
• Edge relationships (wells→plumes, incidents→areas, fauna→habitats).
• 50+ parameter types with realistic value ranges.

Regulatory Applicability

The Regulatory Applicability Assistant performs a first-pass screening of potentially applicable requirements using organization profile, jurisdiction, declared activities, source validity, and territorial competence.

• Four explicit states — applicable, conditional, not applicable when declared, and information missing. Silence never becomes a negative conclusion.
• Source provenance — each finding exposes authority, jurisdiction, version, effective dates, verification date, confidence, and uncertainty.
• Human decision — screenings that require review remain marked, and approval records the reviewer in an audit trail.
• Monitoring candidates — applicable and conditional findings can be carried into follow-up monitoring work.

Results by Campaign / Resultados por Campanha

This panel compares monitoring results across campaigns and points, answering how concentrations evolved over time and how they relate to the selected guideline value.

• Shared filters — select the compound and monitoring points once for both chart and table views.
• Campaign chart — one series per point, canonical campaign order, optional logarithmic scale, dashed guideline value, and explicit gaps without interpolation.
• Censored results — values such as <3 remain verbatim and are shown as open circles at the quantification limit; they are never silently converted into numbers.
• Transposed table and CSV — compare compounds, points, campaigns, units, guideline values, and exceedance markers without relying on color alone.
• Fail-closed warnings — unknown campaigns, unit mismatches, and missing thresholds remain visible instead of being dropped or inferred.

Sustainability Reporting

The Sustainability Reporting Studio builds an evidence-backed reporting workspace, maps reusable facts to selected frameworks, identifies gaps, and prepares a structured content index before export.

• Reporting profile — entity, reporting period, consolidation boundary, audience, and objective are required and validated fail closed.
• Evidence-first disclosures — claims without evidence, conflicting values, and unreviewed equivalence mappings block export.
• Framework mapping — the current catalog supports demonstration mappings for ISSB S1/S2, ESRS/CSRD, CDP, GHG inventory methodologies, TNFD, SBTi, and PCAF workflows. GRI is not included in the current catalog.
• Gap review — coverage is reported against catalogued requirements with owners, status, reusable facts, and blocking or advisory findings.
• Structured export — JSON export becomes available only after blocking findings are resolved; human review and framework submission remain separate.

System Catalog / Catálogo do Sistema

The System Catalog is the live operational inventory of capabilities available in the current ecbyts session. It combines structured Home Grid modules, browser handlers, curated core actions, and the API action registry in one searchable table. It is different from ECBT Catalogs, which manages scientific and data-governance catalogs.

Discovery, search, and export

• Runtime-aware inventory — the list reflects modules that were successfully loaded in the current session; it is not a static marketing list.
• Search — filter by technical name or translated description. The table reports matched, displayed, and total item counts.
• Large catalogs — the table displays up to 500 matching rows and reports truncation; CSV export includes the complete filtered result.
• Deep link — opening the catalog updates the URL to ?tools=system-catalog, so the tool can be shared or reopened directly.

Access and execution safety

Home Grid Module Index

This index is generated from the canonical Home Grid registry. Every executable Home Grid module must resolve to a public documentation section; missing mappings fail the documentation gate.

Maturity is declared per module in the same registry: Experimental modules are usable but may change, lose data compatibility or be withdrawn without notice; Stable modules are covered by the supported scope. The Home screen shows the same "Experimental" badge on those modules.

AI Assistant

The built-in AI assistant provides natural language interaction with the platform through a multi-provider LLM engine.

Capabilities

• 454 dynamic actions — Registry-based dispatch across 45 semantic categories (Model, Analytics, Visualization, Import/Export, Compliance, Infrastructure, and more).
• Natural language commands — "Add a monitoring well at coordinates 100, 50" or "Show me the benzene trend for Well-01".
• Data analysis — Ask questions about your model data and get AI-powered insights.
• Multi-provider support — Works with Cloud providers (OpenAI, Claude, Gemini), local models (Ollama, LM Studio), browser-based (Transformers.js, WebLLM).
• Agentic loop — Complex tasks are broken into a multi-step plan and executed autonomously with tool calling. Supports up to 10 chained actions per turn.
• 3-tier prompt system — System prompt (identity), registry injection (dynamic context), and user message (intent) for precise action resolution.
• MCP integration — External AI agents can interact via the Model Context Protocol server. See MCP Server.

LLM Dynamic Dispatch

The AI Assistant uses a registry-based dynamic dispatch system with 454 registered actions organized in 45 semantic categories. Instead of hardcoded function calls, actions are discovered and executed dynamically based on user intent.

3-Tier Prompt Architecture

Semantic Categories

MCP Server

An ecbyts Model Context Protocol (MCP) server comes in two forms. The hosted server is read-only, runs over the cloud models of the API-key owner and works with any MCP client without installing anything. The local server runs on your own PC over stdio and talks to the api-server.js of the app open in your browser.

• 17 tools — Read the model state, elements and available actions, take a screenshot, add elements and observations, run app actions, plus read-only access to the local repository (files, search, git history).
• Stdio transport — Runs as a local process communicating via JSON-RPC over stdin/stdout. It talks to the local api-server.js (default http://localhost:4000), which drives the ecbyts app open in your browser.
• API key — Create a key in Cloud > API Keys and pass it in ECBYTS_API_KEY. Model tools validate the key and count against the mcp_calls quota of your plan.
• Security — With a key created for an AI agent, tools that write data or run code are refused, and a person on the account has to run that action in ecbyts (two-party approval). Repository tools never read .env*, keys or .git, and never leave the repository folder.

# Start the MCP server (from the repository root)
ECBYTS_API_KEY=ecb_live_... node scripts/ecbyts-mcp-server.mjs

# Configure in Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "ecbyts": {
      "command": "node",
      "args": ["scripts/ecbyts-mcp-server.mjs"],
      "env": { "ECBYTS_API_KEY": "ecb_live_..." }
    }
  }
}

Reports

Generate professional reports from your environmental model data.

• PDF Export — Create formatted reports with charts, tables, maps, and compliance summaries.
• DOCX Export — Generate editable Word documents for further customization.
• Report Editor — Customize report sections, add narrative text, and select which data to include. Supports filter presets.
• Drawing Plate — Export technical drawings with title blocks and scales.
• Multi-Report Manager — Maintain multiple report templates with tree-view navigation.
• Access via File > Drawing Plate or through the report panel.

Governance

Project management tools for environmental remediation contracts.

• Contracts — Track environmental service contracts with scope, dates, and milestones.
• WBS (Work Breakdown Structure) — Organize remediation activities hierarchically.
• EVA (Earned Value Analysis) — Track project performance: planned vs. actual cost and schedule.
• Project Registry — Central directory of projects with metadata and status.

Timekeeper

Cross-project time tracking panel embedded in the Constellation HUD. Log hours against projects, phases, and resources without leaving the modeling environment.

IoT Sensors

Connect real-time environmental sensors to your digital twin for continuous monitoring.

• Link sensors to elements for automatic observation updates.
• Configure polling intervals and alert thresholds.
• Sensor data feeds into the same analytics pipeline as manual observations.

Guided Tours

Interactive step-by-step tutorials that guide you through platform features.

• Task-oriented picker — Filter by your role and the job you want to learn; each card identifies its expected artifact and safe execution mode.
• Environmental-agency practices — Triage, chain of custody, inspection, licensing, technical opinion, independent review, and audit-package tours use synthetic data and stop before administrative mutation.
• Communicate tour — agency-communicate-sharing teaches people/relationships, minimum dataset slices, purpose, classification, online access versus portable ECBT keys, review, recovery, and redacted receipts.
• Honest completion — A visible first step is not completion; required artifacts, evidence checks, all stages, error recovery, and cleanup must pass.
• Access via More > Guided Tours or the Tour Picker.

▶ Subcontractor Data Guide

This guide follows the route a subcontracted operator actually walks in the product, from receiving an assignment to handing a batch over. Each stage names the live screen, the guided tour that teaches it, and the limit you have to work around today. Where a screen does not exist, the guide says so instead of describing an intention.

The route has ten stages. The last one has no screen in the product today, and that is stated in full rather than left out.

1. Receive the assignment and the access
2. Inventory the documents
3. Digitize and check
4. Import the EDD
5. Bring in GIS and CAD data
6. Enter readings by hand
7. Validate and correct
8. Change and remove records
9. Hand over for review
10. Close the engagement

Before you save or send anything, read the destination matrix under Import / Export: it lists every authorized destination, what each one is for, and what you must check after writing. This guide points back to that matrix instead of repeating it.

• Save and recover data — authorized destinations and their checks

1. Receive the assignment and the access

• Where — Export > Resource Shares opens the live sharing panel. It lists the shares that already exist and the fields of a new one: resource, grantee, purpose, scope, classification and expiry date, with a preview before granting.
• What you do — Read the share aimed at you before opening any data: which resource, for what declared purpose, under which classification, and until when. Work only inside that scope.
• Guided tour — share-access-assignment walks the real panel and stops before submitting. It also shows the denial path on purpose, because the denial is part of the task.
• Limit today — The panel only mirrors your role: when your role cannot share, the grant button is disabled and a gate message appears. The decision that actually counts is enforced by the server, not by the button state. The revoke button in the list is disabled the same way.
• Limit today — The Communicate practice tour agency-communicate-sharing runs on a synthetic training panel with simulated values. It is a rehearsal, not the live share.
• See also Ownership and Access and Organization Management.

2. Inventory the documents

• Where — Data > Project Files opens the Files tab. The table lists name, extension, size, source, tags and last update, with Preview, Download, Re-import, Tag and Delete on each row. Filters cover extension, source and scope, plus a tag box and a sort order.
• What you do — Register everything you received before transcribing anything. Drag a file onto the drop zone to register it without ingesting it, then tag it so the batch can be found later.
• Guided tour — document-inventory.
• Limit today — The stored record keeps filename, MIME type, extension, size, storage path, SHA-256 checksum, tags, source, status, scope and dates. It has no document version, no rights or licence field, and no page or sheet count. Keep the version and the usage rights outside the panel — in the file name and in your own transmittal — because the product will not keep them for you.
• Limit today — Since there is no version field, the checksum is what identifies a revision. Two files with the same name and different checksums are different documents; treat them as such.
• See also Files Module.

3. Digitize and check

• Where — Data > Import Data handles PDF and DOCX reports in a split view: source document on the left, extracted data on the right with source-grounding highlights. Field photographs go through Data > Photo Log, which reads EXIF GPS and places the photo as a marker in the scene.
• What you do — Check the extraction against the page before confirming: compare the extracted table with its source, follow the page divider, read the confidence indicators, and look at what the review marked as excluded rather than only at what it accepted.
• Guided tour — document-import-pdf, extended to cover the two checking aids the review screen already has.
• Limit today — The individual review controls have no stable anchors, so the tour stops at the review container instead of pointing at a control that could move. Extraction can miss context: the source document, not the extracted table, remains the evidence.
• See also Document Assessment and PhotoLog.

4. Import the EDD

• Where — Data > Import Data runs the ingestion wizard for XLSX and CSV: choose the file, map columns to elements, parameters and campaign dates, answer the domain decisions, then review and confirm.
• What you do — Confirming does not write into your model directly. The wizard builds a candidate model and opens the comparison screen with your current model on one side and the imported data on the other, so the decision is explicit.
• Guided tours — spreadsheet-import-wizard, edd-import-export-complete and data-loading-from-scratch. The tour cards offer synthetic training examples for download, including a tabular EDD workbook.
• Limit today — A tabular CSV or a training workbook is a subset, not a complete laboratory EDD profile. Do not read a successful training import as proof that a full profile will map.
• Limit today — A mapping plan is only executed after it is explicitly approved; an unapproved plan is rejected rather than applied quietly.
• Limit today — The wizard blocks its final button only in one case: when you asked it to clear the current model and to export a backup first, and that backup has not been downloaded yet. In every other configuration nothing forces you to hold a copy, so take one yourself.

5. Bring in GIS and CAD data

• Where — Data > DXF imports CAD site plans as blueprint elements, parsing layers, polylines, circles, text and blocks. Data > Georeference and the Map Picker set the site position and the coordinate system.
• What you do — Declare the coordinate system before processing. The wizard accepts explicit local coordinates, so a purely local exercise does not need a geographic system invented for it. Projected coordinates are converted with the platform projector, and the original values and system are kept alongside the converted pair.
• Guided tours — import-dxf-blueprint and map-picker-geolocation. The training boundary example is a closed rectangle of 10 by 5 metres on a training layer, 50 m², in local coordinates.
• Limit today — Never let an unknown coordinate pass as a known datum. If the source does not declare its system, the import must fail rather than guess one.
• Limit today — Geographic metadata stored on an element is not automatically refreshed when you move that element in the scene. After moving anything, check the exported coordinates instead of trusting the stored pair.
• See also Spatial Blueprint (DXF), Map Picker and Aerial Georeferencing.

6. Enter readings by hand

• Where — Data > Data Entry Matrix, also reachable from the Data Entry tab of the bottom panel. Elements are the rows, parameters are the columns, units default per column, and values are checked against the compliance thresholds as you type.
• What you do — Use it for a batch of readings instead of opening one modal per observation. Enter the campaign date with the reading; a reading without a date is incomplete, not current.
• Guided tours — batch-data-entry, add-observation and add-planned-readings.
• Limit today — An empty analytical value stays empty; it is not turned into a zero, and a measured zero is preserved as a measurement. A missing date is not replaced by today's date. Do not fill either one to make a row look complete.
• Limit today — A red cell means the value crossed a configured threshold. It does not mean the value is wrong, and a cell that is not red has not been proven right.
• See also Data Entry Matrix and Observations.

7. Validate and correct

• Where — Compliance Validation carries the built-in regulatory thresholds; the Domain Validator loads profiles in JSON; Data Audit looks for anomalous distributions.
• What you do — Run the batch validation, export the result as CSV, correct at the source, and run it again.
• Guided tours — data-quality and regulatory-compliance.
• Limit today — The position reported in an error is the one-based row of the validated batch, not necessarily the row of your original spreadsheet. Source file, sheet and row appear as separate columns only when the import supplied them, and stay blank when it did not.
• Limit today — An unknown rule type stops the run with an explicit error instead of being accepted silently; fix the profile before running again. A failed run invalidates the previous report, so never hand over a report from an earlier attempt.
• Limit today — Validation checks rules, not truth, and the audit tools flag suspicion, not proof. A clean report is not an attestation that the data is correct.
• See also Compliance Validation, Validation Profiles, DAMA Data Quality and Data Audit.

8. Change and remove records

• Where — Edit elements and observations from their own panels; use the history and recovery actions to inspect and undo recent changes; use the comparison screen to review a whole set of differences before applying it.
• What you do — Describe the change before making it: which records, which campaign, and why. Removal is a data decision, not a cleanup gesture.
• Guided tours — edit-delete-observation and edit-element-properties.
• Limit today — Recovery is only as good as the last persisted state, and the local resume copy lives in this browser on this device: clearing browsing data can remove it. A portable copy in an authorized destination is the only recovery you control.
• Limit today — The bulk-acceptance rules described in the note above apply here too, because the same comparison screen is used to apply a reviewed set of changes: a bulk button never deletes, and a per-card choice of the imported side deletes without asking.
• See also History, Undo and Recovery and Model Merge and Diff.

9. Hand over for review

• Where — Reports produce the PDF, DOCX and drawing-plate outputs; Issues 3D anchors a non-conformity to a point in the scene so the reviewer sees where it is; Resource Shares gives the reviewer scoped access to the data itself.
• What you do — Deliver two things that agree with each other: the data saved to an authorized destination, and the report bound to that same version. Reopen the saved copy before you declare the delivery done.
• Limit today — A report presents results; it does not replace editable data, and it is not a backup. Sharing follows permissions and does not necessarily create an independent copy for the reviewer.
• Limit today — There is no delivery receipt in the product. Nothing marks a batch as submitted for review, so record the handover, its date and the checksum of what you sent outside the product.
• See also Reports, Issues 3D, Governance and the destination matrix.

10. Close the engagement

• What exists instead — A share carries an expiry date and can be revoked from the sharing panel by whoever holds that permission. Let the access lapse or ask for it to be revoked, and confirm in the list that it is gone.
• What exists instead — The Files tab keeps the checksum of every registered file. Record the checksum of each delivered file: it is the only identity the product stores for a document.
• What you do — Export a portable copy to an authorized destination, reopen it to confirm it loads, and register the closure outside the product: what was delivered, when, to whom, and against which checksums.
• Limit today — Because closure is recorded outside the product, two people can disagree about whether a batch is finished and nothing in the model settles it. Agree on the closure record before the access expires, not after.

Map Picker

Interactive georeferencing tool for setting your site's real-world location.

• Click on a map to set the UTM origin for your environmental model.
• Automatic UTM zone and CRS detection (including SIRGAS 2000 for Brazilian sites).
• Aerial imagery overlay for spatial context.
• Available as an init mode from the Welcome Screen or via View > Map Picker.

Multi-Model Tabs

Work with multiple environmental models simultaneously — each tab is an isolated namespace for elements, campaigns, scenes, and analytics.

• Independent state — Elements, observations, and interpolations in one tab don't leak into another.
• Cross-tab lock via BroadcastChannel — Prevents concurrent edits of the same model across browser tabs.
• Per-tab autosave — Each tab persists to a dedicated IndexedDB lane.
• ECBT round-trip preserves tab identity — Export and re-import keeps the tab's logical model separate.

Uncertainty (UNC-001 — GUM Tier 1)

First-order uncertainty propagation for environmental measurements following ISO GUM (Guide to the Expression of Uncertainty in Measurement).

• Propagation — Sum / product / linear formulas with covariance-aware combined standard uncertainty.
• Quality badge — Matrix-agnostic classifier (soil / water / air) decorates every observation with a data-quality indicator.
• ECBT v3 envelope — Uncertainty metadata travels inside exported keys (opt-in via flag).
• Visible in the Uncertainty Hub panel (ribbon > View) and inline in Data Entry Matrix.

Taxonomy / Data Dictionary

Regulatory taxonomy layer that adds auxiliary, standard-aligned fields to elements (EPA WQX, ABNT NBR, CETESB DD-256, CONAMA 420).

• Field resolver — Resolves a field by {taxonomy, key, locale} and returns label, unit, valid-range, citation.
• Picker modal — Pick fields from regulatory standards without leaving the form.
• Domain-aware validation — Combines with Validation Profiles for end-to-end compliance checks.

Historical Map Upload & Georeferencing

Upload raster maps (PNG/JPEG) and georeference them with 4+ control points using least-squares affine transform. Includes an OCR pipeline for elevation extraction from topographic maps.

• 4-point GCP workflow — Click to add control points; enter pixel (X, Y) and UTM (Easting, Northing) for each.
• RMS gate 5 m — Validates georef quality per CETESB mapping guidelines before accepting.
• TFW world-file export — ESRI-compliant sidecar for GIS interoperability.
• Contour extraction — Marching-squares + edge chains turn isolines into generic:isoline elements in the 3D scene.
• OCR elevation pipeline — elevationClassifier reads numeric labels from scanned topographic maps (BR and US formats), contourLabeler matches labels to contour polylines, contourGeoreferencer assigns Z values, simplifies polylines, and exports georeferenced isolines as GeoJSON.
• GeoJSON export — Georeferenced contours exported as FeatureCollection for GIS interoperability.
• Ribbon > Data > Historical Map Upload.

PhotoLog

Field photo registry with EXIF GPS extraction, AI vision analysis, and 3D scene markers.

• Capture sources — Camera, upload, clipboard paste.
• Offline-first — IDB stores photos locally; Supabase sync when online.
• EXIF GPS — Auto-positions photos as 3D markers in the scene at their capture location.
• AI vision analysis — Describes the photo, detects families (buildings, vehicles, vegetation), flags anomalies.
• Access via Data > PhotoLog or the PhotoLog button in Files.

Technical Diagrams (ISA S5.1)

Canvas-based technical diagram editor with process-industry symbology (ISA S5.1 / P&ID / FSM / DFD).

• Drag-and-drop symbol palette (tanks, valves, pumps, instruments, transmitters).
• Connections with automatic orthogonal routing.
• Pan, zoom, grid snap.
• Export PNG or SVG for reports and proposals.

Impact Estimator

Environmental impact estimator with financial formulas (passivo / ativo) traced to CONAMA, CNJ, and INSS benchmarks. Integrates with UNC-001 Monte Carlo for probabilistic risk quantification.

• Scenario comparison — Run baseline vs. intervention and quantify net benefit via compareScenarios.
• Family aggregation — Roll up impact across wells, plumes, tanks, etc. using aggregateByFamily.
• Traced benchmarks — Every number carries a citation (regulation or jurisprudence).
• Uncertainty integration — Wires into UNC-001 Monte Carlo (soil/groundwater/occupational matrices) to produce IC95 confidence intervals, probExceedance, and risk class (green <5% / yellow <20% / red ≥20%).
• Results rendered as HUD card with risk class indicator. Integrates with the EIS score and Environmental Valuation.

Environmental Valuation (ENV-VAL-001)

Project valuation engine for environmental investments using VPL (NPV), CRF (capital recovery factor), VPLA (equivalent annual value), and MAC curve.

• VPL / NPV — Discounted cash-flow of remediation costs vs. avoided passivo.
• CRF — Annualized capital charge for equipment + infrastructure.
• VPLA — Equivalent annual value for comparing projects of different lifespans.
• MAC curve — Marginal abatement cost curve for multiple interventions.
• Visible as a HUD card (env-valuation-hud-mount) and in project reports.

Cost Analysis (CAPEX + OPEX)

Cost roll-up across the PDPL-U hierarchy (site → area → zone → element) with dashboard visualization.

• Four-level roll-up — L1 site, L2 area, L3 zone, L4 element.
• CAPEX vs. OPEX split — Separate capital and operational aggregates.
• Cost Centers — Assign elements to cost centers for accounting and EVA (Earned Value Analysis).
• PDF export — Ready-to-sign proposals with cost charts.

What-If Scenario Comparator

Answers the question what changes if I alter part of my process? without rebuilding the model. The comparator copies your model into an alternative scenario, applies the change to the copy, and shows base | alternative | Δ side by side for CAPEX, OPEX, ECBT Score and the UN Sustainable Development Goals. Your original model is never modified.

• Where — Open the More menu, choose ECBT Score (Area Verdict), then the Scenarios button.
• Main action — Choose the process subtype and move the throughput, recovery and yield controls inside the range curated for that subtype; every range carries its published source. Undo reverts the last change, and the session history stays in your browser — it is never stored on the server.
• Limit — Changing a rate moves the physical balance, not CAPEX, OPEX or ECBT Score: those follow the cost lines of the element, and a rate is not a cost line. The comparator supports a decision; it does not replace professional validation or regulatory review.

A banner always states whether the figures come from your real model or from labelled example data, which you have to accept explicitly before any demonstration number appears. The same provenance travels on every row of the CSV and Excel exports, so a spreadsheet detached from its context can never pass example figures off as measurements. Four export shapes are available: CSV, JSON, Excel and Markdown.

Missing information reads as no data, never as zero, and the panel separates two reasons: your model lacks the figure, or the conversion factor is still waiting for a published source — in which case the panel names the source it needs and leaves the column deliberately empty. When a measured physical flow changes but no published factor can convert it into an impact, the flow change is reported on its own channel instead of disappearing behind a no-data label.

Purpose Module

Track the real-world EIS impact of every modeled action and collect micro-feedback from stakeholders.

• Purpose snapshots — Capture EIS score over time and correlate with interventions.
• Micro-feedback toast — Lightweight thumbs-up / thumbs-down on outputs (reports, AI suggestions) for RLHF signal (F4.6).
• Community impact — Roll up individual snapshots into aggregate environmental outcomes.

Automation Bot Manager

Event-driven automation engine that reacts to file uploads, AI photo tags, map interpolation completion, and other triggers.

• Triggers — File upload, campaign import, AI photo classification, interpolation refresh, schedule.
• Actions — Run validation profile, create element, notify stakeholder, export report, enqueue pipeline.
• Chainable — Multi-step workflows with conditional branching (BPMN integration).
• Access via Tools > Automation in the ribbon.

Model Radar (Broadcasting)

Broadcast your model's state to stakeholders via time-limited share_code URLs — no account required for viewers.

• Broadcast profiles — Define what to share (layers, cameras, analytics) and for how long.
• Heartbeat — Viewers see live updates when the model changes.
• Public broadcast page — broadcast.html?code=<share_code> served read-only.
• Roles — Optional downgrade to observer-only mode for regulators and auditors.

Sample Files (Public Catalog)

Read-only catalog of reference files hosted on Supabase Storage — aerial images, templates, demos — available to every user without authentication.

• Aerial reference — Default aerial photo for overlay fallback, AI recognition, or raster upload demos.
• Use in dropdown — Select a consumer action (aerial overlay, raster upload, AI recognition, automation input) and the sample is auto-piped into the right modal / handler.
• No login required — Samples are public CDN URLs; workable offline in combination with Service Worker cache.
• Appears in the Files panel alongside your private files, tagged sample.

DataStudio (SQL over your model)

Run client-side SQL queries against your environmental model — elements, campaigns, observations, edges, layers — without round-tripping to a server.

• Schema panel — Browse all queryable tables with column types.
• Query editor — Syntax-highlighted SQL editor with autocomplete for tables and columns.
• Results grid — Tabular results with sorting, filtering, and CSV export.
• History — All runs persisted locally; re-run or bookmark queries.
• Shell is modular: Collection, Processing, Analytics, and Communicate compose the interface.
• Manage people — Record the institutional relationship separately from administrative permissions.
• Share datasets — Select a minimum dataset slice, recipient, purpose, classification, permission, and expiration, then review before confirming.

UI Customization

Personalize the interface: fonts, color palettes, density, home-screen card layout, and default panels.

• Fonts — Choose from curated typefaces optimized for technical readability.
• Palette — Dark, light, or custom palettes with tokens applied globally via CSS variables.
• Density — Compact / comfortable / spacious spacing.
• Home cards — Reorder and toggle the home-screen cards relevant to your workflow.
• Settings persist in localStorage.ecbyts-customize.

Error Reporting & Bug Reports

Capture runtime errors and user-submitted bug reports with automatic screenshot, stack trace deduplication, and Supabase ingest.

• Global error boundary — window.onerror and onunhandledrejection log to a buffer, flushed in batches.
• Bug report modal — User describes the issue; screenshot captured automatically via DOM snapshot.
• Dedup & classifier — Collapses identical stack traces; classifies as bug / feature request / question.
• Admin inbox — Reports visible in the admin module with triage workflow.
• LGPD-aware: PII is redacted from DOM screenshots before upload.

Libraries Marketplace (v2)

Install and monetize curated libraries of environmental data, ML models, pipelines, and AI services — all under AGPL-3.0-compatible licenses.

• Marketplace — Browse public libraries with reviews, ratings, and preview before install.
• Installed libraries — Manage versions, permissions, and update notifications.
• Import file — Side-load a .ecolib library package into your workspace.
• AI Service listings — Automated API execution billed per output token in $ECBT.
• Consultoria Diretoria — Human-hours bookable at R$ 500/HH (4 h/week, 4 h minimum per contract).
• Access via the Libraries galeria in the ribbon.

Inspector

Review the selected element, its observations, relationships, campaigns, hierarchy, costs, and operational metadata in one side panel.

• Where — Open from the Actions workspace, element cards, context menus, or the selected element panel.
• Main action — Select an element, inspect linked records, then jump back to the model or related data.
• Limit — Inspector content depends on the active model and selected element; empty selections should not imply missing data.

Simulation Lab

Run local environmental simulation routines with explicit parameters, consent, and browser-side execution boundaries.

• Where — Open from simulation actions, modal launchers, or supported workflow steps.
• Main action — Choose a model, review parameters, accept execution responsibility, and run the simulation.
• Limit — Prototype solvers are educational and must be validated by qualified professionals before engineering use.

AI Agents

Use specialized assistants for general questions, regulatory analysis, campaigns, and occupational/environmental workflows.

• Where — Open from assistant controls, agent menus, command palette actions, or AI panels.
• Main action — Pick the agent scope, review the proposed action, and confirm before write operations.
• Limit — Agent output is AI-generated guidance and does not replace professional validation or regulatory review.

Document Assessment

Assess uploaded environmental documents for structure, evidence, decisions, coordinates, labels, and extractable observations.

• Where — Use from ingestion, file preview, assessment actions, or document track panels.
• Main action — Load a document, run assessment, review extracted findings, and accept or reject decisions.
• Limit — OCR and AI extraction can miss context; keep the source document as the evidence anchor.

Chemistry Registry

Search, normalize, and validate chemical parameter metadata such as names, aliases, and CAS references.

• Where — Open from chemistry actions, parameter editors, or validation workflows.
• Main action — Match a parameter, review aliases and identifiers, then reuse the normalized name in observations.
• Limit — Registry matches support data quality; legal limit interpretation still depends on the selected framework.

Field Metadata

Attach provenance, confidence, source, and validation notes to fields that affect model quality and auditability.

• Where — Field metadata appears near editable fields, popovers, and selected data cells.
• Main action — Open the metadata popover, review source information, and add traceability notes when needed.
• Limit — Metadata improves audit trails only when users keep source and decision notes current.

Model Merge and Diff

Compare two model states, inspect changes, and merge accepted differences with explicit review.

• Where — Open from merge actions, import flows, or collaboration review tasks.
• Main action — Load base and incoming models, inspect changed entities, then accept or reject each group.
• Limit — Never merge regulatory evidence blindly; review geometry, timestamps, and source ownership first.

Notifications

Review operational alerts, system messages, marketplace updates, and priority events generated by the workspace.

• Where — Use notification panels, badges, top-bar indicators, and contextual alerts.
• Main action — Open the alert, inspect priority and source, then navigate to the affected object or workflow.
• Limit — Some notifications depend on Supabase access and may be unavailable offline.

Notification Rules

Configure thresholds and rule-driven alerts for data quality, compliance, sensors, marketplace events, and operational changes.

• Where — Open from notification settings, governance controls, or advanced configuration actions.
• Main action — Define the trigger, scope, severity, and destination before enabling the rule.
• Limit — Rules should be tested with known data before they are used for operational escalation.

Wallet and Credits

Manage credits, payments, premium access, marketplace transactions, and blockchain-linked account actions.

• Where — Open from wallet actions, account controls, credits badges, marketplace flows, or premium gates.
• Main action — Review balance, transaction context, and any signing or payment requirement before proceeding.
• Limit — Blockchain and payment actions must be verified against the active environment before use.

History, Undo and Recovery

Inspect recent changes, undo safe operations, and recover workspace state after editing, import, or autosave events.

• Where — Use the ribbon history actions, model status indicators, and recovery prompts.
• Main action — Review the change description, confirm the affected objects, and apply undo or recovery.
• Limit — Destructive operations require explicit confirmation; recovery is only as good as the latest persisted state.

Imagery Layers

Add, inspect, and manage raster imagery used as aerial context, georeference support, or visual evidence in the model.

• Where — Open from imagery actions, raster upload, aerial tools, or scene layer controls.
• Main action — Add an image, align it to the model, adjust visibility, and document its source.
• Limit — Cross-origin imagery can taint canvas analysis; keep source metadata for auditability.

Organization Management

Manage organization-level workspace context, members, scopes, and model ownership boundaries.

• Where — Open from organization actions, account menus, workspace loader, or admin-linked flows.
• Main action — Select the organization context, review membership, and switch model scope deliberately.
• Limit — Organization operations may require hosted services and permissions outside a local-only workspace.

Ownership and Access

Review who owns a model, who can edit it, and which actions require role checks or explicit transfer.

• Where — Open from ownership actions, model settings, sharing flows, and role-guarded panels.
• Main action — Confirm owner, role, and target scope before changing access or transferring responsibility.
• Limit — Access decisions affect auditability and legal defensibility; avoid ambiguous ownership states.

Presets

Apply saved configurations for model views, workflows, validation profiles, visuals, and operational defaults.

• Where — Open from preset actions, scene controls, validation setup, or workflow launchers.
• Main action — Choose a preset, preview the affected settings, and apply only to the intended scope.
• Limit — Presets accelerate setup but should not override site-specific technical judgment.

Health Export

Export occupational health, exposure, or monitoring data in a structured package suitable for review and integration.

• Where — Open from health export actions, occupational modules, or compliance workflows.
• Main action — Select scope, anonymization mode, period, and output format before exporting.
• Limit — Health data can be sensitive; validate LGPD/privacy requirements before sharing files.

Accessibility

Use accessibility helpers for labels, keyboard flow, modal behavior, and form readability across the interface.

• Where — Accessibility behavior appears in forms, modals, custom controls, and validation feedback.
• Main action — Navigate with keyboard, verify labels, and keep focus movement predictable.
• Limit — Automated checks do not replace manual testing with real assistive technologies.

Background Analysis

Compare observations against background conditions to support environmental interpretation and anomaly review.

• Where — Open from analytics, hypothesis testing, or parameter review flows.
• Main action — Select reference data, compare current readings, and review flagged deviations.
• Limit — Background definitions are technical assumptions and must be justified for each site.

Decision Rules

Define deterministic rules that classify data quality, compliance, recommendations, or next actions from model evidence.

• Where — Open from governance, validation, uncertainty, or advanced rule configuration panels.
• Main action — Choose inputs, thresholds, rule priority, and expected outcome before enabling the rule.
• Limit — Rules must remain explainable and traceable; avoid hidden logic for regulatory decisions.

DAMA Data Quality

Evaluate data quality dimensions using DAMA-inspired criteria and link issues back to source fields and records.

• Where — Open from data quality, validation, ingestion, or EIS-adjacent workflows.
• Main action — Run checks, inspect failed dimensions, and resolve source data issues before export.
• Limit — Quality scoring indicates risk; it does not certify technical correctness by itself.

ECBT Validator

Validate model packages, exported data, and imported structures against ECBT expectations before use or sharing.

• Where — Open from import/export, validation, or advanced model integrity actions.
• Main action — Select a model or package, run validation, then fix blocking errors before continuing.
• Limit — Passing schema validation does not guarantee that domain assumptions are correct.

Ledger Summary

Summarize integrity records, hashes, signatures, and audit-relevant events linked to the active model.

• Where — Open from blockchain, audit, governance, or model integrity workflows.
• Main action — Review recorded events, compare hashes, and export supporting evidence when needed.
• Limit — Ledger summaries prove recorded state, not the technical truth of unverified source data.

Parameter Groups

Organize parameters into operational groups for filters, reports, analytics, and regulatory interpretation.

• Where — Open from parameter configuration, SAO matrices, analytics, or report setup.
• Main action — Create or select a group, assign parameters, and reuse the group in analysis flows.
• Limit — Grouping changes how data is interpreted; keep names and inclusion criteria explicit.

SAO Heatmap

Visualize source-activity-object relationships as heatmaps to identify concentration, exposure, or management priorities.

• Where — Open from SAO tools, analytics, or environmental matrix review flows.
• Main action — Select matrix, parameter, scope, and campaign range, then inspect hotspots.
• Limit — Heatmaps are prioritization aids; review raw observations before making decisions.

SDG Alignment

Map environmental and occupational evidence to Sustainable Development Goal indicators and confidence levels.

• Where — Open from EIS, governance, ESG, or impact reporting workflows.
• Main action — Review mapped SDGs, inspect confidence, and document why each alignment applies.
• Limit — SDG alignment is a reporting interpretation and should be backed by auditable evidence.

Spatial Clustering

Cluster spatial observations or document-extracted locations to identify groups, duplicates, and likely site patterns.

• Where — Open from ingestion, spatial tools, document assessment, or analytics flows.
• Main action — Choose spatial inputs, run clustering, and review grouped records before accepting them.
• Limit — Clusters are sensitive to distance thresholds, projection, and coordinate quality.

Optimization

Explore candidate decisions, resource allocation, or scenario improvements when a workflow exposes optimization controls.

• Where — Open from optimization actions, scenario workflows, or cost and remediation decision panels.
• Main action — Define objective, constraints, candidate options, and review recommended trade-offs.
• Limit — Optimization output is decision support; constraints and assumptions must be reviewed before adoption.

How to Contribute

ecbyts is an open-source project distributed under AGPL-3.0-only. For the authoritative legal terms, refer to the repository LICENSE file. Contributions are welcome from diverse backgrounds — you do not need to be a software developer to help. Below are five contributor profiles with guidance tailored to each.

▶ Developer

▶ Dev Prompt Toolkit

▶ Vibe Coder

▶ Regulatory Body

▶ End User

▶ Financial Sponsor

Admin Module

Comprehensive administration panel for platform operators covering 14 management areas. Access is restricted to users with the admin role in Supabase.

Management Areas

• Audit Trail — Every admin action is logged with timestamp, actor, and before/after state for LGPD compliance.
• Dashboard KPIs — Real-time metrics: active users, MRR, storage usage, AI call volume, error rates.
• Bulk Operations — Mass quota adjustment, user exports, subscription migrations.
• Feature Flags — Toggle experimental features per user or tier without redeployment.

Data Sovereignty & Transparency

ecbyts is built on the principle that environmental data is a public asset. The platform provides a framework for radical transparency and friction-less data sharing between regulators, stakeholders, and AI systems.

• Universal interoperability — JSON-based schemas and alphanumeric ECBT keys ensure data is never siloed. Transitioning between platforms is facilitated by open-format standards.
• Cryptographic integrity — Trust is mathematically enforced. Every record is secured via SHA-256 hashing and provenance chains, with optional blockchain notarization.
• Machine-centric design — Every data structure is strictly typed, enabling LLMs to perform complex reasoning, querying, and automated reporting without custom adapters.
• Regulatory alignment — First-class support for Brazilian (CONAMA, CETESB, IBAMA) and international standards ensures compliance is built into the data model.

ESG Economic Framework

ecbyts integrates a reporting-based incentive layer grounded in ESG conceptual models. This structure enables the tokenization of environmental performance and alignment with international H&S protocols.

• Performance-Indexed Assets — Proposed cryptocurrency framework where asset valuation is indexed to corporate socio-environmental metrics.
• Monetization Pathways — Data structures designed for market-based pricing, subscription models, and participant ecosystem integration.
• Post-IPCC Integration — Postulated integration of environmental digital twin assets with updated IPCC regulatory and reporting protocols.

Security & Data Integrity

Multi-layered security architecture protecting environmental data integrity and user privacy. 4-phase hardening roadmap from CAPTCHA to fraud detection.

• Content Security Policy (CSP) — Restricted origins for scripts, images, and connections. No wildcard CORS.
• API server isolation — Bound to loopback only. CORS restricted to server origin.
• ECDSA P-256 key vault — Private keys wrapped with AES-GCM encryption (never stored as plaintext).
• LLM API key encryption — User API keys encrypted with per-user PBKDF2 salt.
• hCaptcha CAPTCHA — Bot protection on login, registration, and password reset forms. Invisible mode for authenticated users.
• MFA / TOTP — Optional multi-factor authentication via authenticator apps (Google Authenticator, Authy). TOTP with 6-digit codes and 30s rotation.
• LGPD Audit Trail — Full data processing log for Brazilian General Data Protection Law compliance. Records consent, data access, and deletion requests.
• Credential fraud detection — Behavioral analysis detecting suspicious login patterns, impossible travel, and credential stuffing attempts.
• EcoTools sandbox — External tools run in iframe without allow-same-origin.
• Atomic quota enforcement — Supabase RPC with row-level locking prevents race conditions.
• Security logging — Structured logs with automatic sensitive field stripping.

Authentication & SSO

Supabase-powered authentication with multiple sign-in methods.

• Social / OAuth sign-in — Google, GitHub, and Microsoft accounts through Supabase OAuth. These are consumer identity providers: convenient, but they are not corporate SSO and do not map a company directory onto organization roles.
• Email/password — Traditional registration with email verification.
• Login throttle — Rate-limited to 5 attempts per 10 minutes per IP. Exponential backoff with user-friendly countdown.
• MFA enrollment — Optional TOTP-based multi-factor authentication via the security settings panel.
• LGPD compliance — Consent management, data portability (JSON export of personal data), and right-to-deletion enforcement.
• Academic credential verification — Upload diplomas for EIS score credential multiplier (verified via Gemini Vision).
• Professional tier — Stripe checkout for premium features and higher usage quotas.

Keyboard Shortcuts

Environmental Glossary

Common Parameters

Environmental parameters available for observations. Custom parameters can also be added.

Technology Stack

Data Model (ECBT Schema)

Models are represented as validated JSON objects with the following top-level structure:

{
    "ecbyts": "0.2.0",
    "timestamp": "2026-02-07T12:00:00Z",
    "project": {
        "name": "Site Investigation",
        "author": "Environmental Engineer",
        "coordinateSystem": { "system": "UTM", "zone": 23, "hemisphere": "S" },
        "areas": [{ "area": "Area A", "subarea": "Subarea 1" }]
    },
    "elements": [{ "family": "well", "id": "el_1", "name": "PM-01", ... }],
    "campaigns": [{ "id": "camp_1", "name": "Q1 2026", "startDate": "2026-01-01" }],
    "scenes": [{ "id": "scene_1", "name": "Overview", "viewStart": {}, "viewEnd": {} }],
    "families": {},
    "edges": [{ "id": "edge_1", "sourceId": "el_1", "targetId": "el_2", "type": "monitors" }],
    "areasTree": []
}

• elements — Array of site elements with family, position, properties, and nested observations.
• campaigns — Sampling events with dates, team info, and visibility toggles.
• scenes — Saved camera viewpoints with start/end states and per-element visibility.
• edges — Directed relationships between elements (monitors, flows_to, contains, etc.).
• families — Custom family definitions extending the default PDPL-U set.
• areasTree — Hierarchical project organization (controladora > area > subarea).

Discoverable Panels — Painéis Descobríveis

Panels that ship with ecbyts but have no fixed toolbar home — reach them from the top ribbon More menu (menu Mais). This list is generated from the panel discovery registry, so it never drifts from the code. Painéis que existem no ecbyts mas não têm lugar fixo na barra — abra-os pelo menu Mais do ribbon superior.

Admin — Administração

Data — Dados

Monitoring — Monitoramento

Governance — Governança