Reports

[ngoiyaeric]

Compliance documents and standards from mining exploration and agriculture that typically involve or require GIS (Geographic Information Systems), spatial data, maps with coordinates, geospatial layers, or digital mapping:

These emphasize location data (coordinates, boundaries, datums/projections), GIS-compatible formats (e.g., shapefiles, KML/KMZ), farm/field maps, tenure boundaries, disturbance/reclamation areas, resource modeling, and traceability.

Mining Exploration

• Digital mineral exploration data submissions / exploration reports — Australian national guidelines (and many state/territory equivalents) require geospatial data (drill holes, samples, geology, models, maps) labeled for GIS display, including datum, projection, coordinates, and accuracy. GIS data formats are specified by agencies.
• Program for Environment Protection and Rehabilitation (PEPR) / equivalent exploration or mining plans — Spatial mapping of activities, disturbance, and rehabilitation; often includes GIS layers.
• Annual Reclamation / Compliance Reports — Explicit geospatial file submissions (e.g., shapefiles of disturbance and revegetated areas in BC, Canada, with specific coordinate systems and attributes matching reported tables/maps).
• Technical Report Summaries / CRIRSCO-aligned resource reports (JORC, NI 43-101, S-K 1300, PERC, etc.) — Maps of tenements, geology, drill collars, resource models, and infrastructure; spatial data underpins estimates and public disclosure. GIS is standard for visualization and modeling.
• Environmental Impact Assessments (EIA) / Environmental Assessment documents — Spatial analysis of impacts, baselines, and mitigation (land use, hydrology, sensitive areas).
• Reclamation/rehabilitation plans + financial assurance filings — Mapped disturbance, progressive reclamation areas, and post-mining land use.
• Notices of Intent / Plans of Operations (e.g., BLM 43 CFR 3809) and mining claim/tenement filings — Location maps, boundaries, and spatial validation of claims or permits.
• Related ISO/management systems — ISO 14001 (environmental aspects often mapped spatially); supporting data under ISO 9001/17025 for sample locations and QA/QC.

GIS is routinely used for tenure management, prospectivity mapping, environmental monitoring, and compliance dashboards in modern mining.

Agriculture

• Organic certification documents (USDA NOP, EU Regulation 2018/848, and equivalents) — Required farm/field maps showing boundaries, organic/in-conversion/conventional areas, buffer zones, field sizes/names, neighboring land use, landmarks, and (increasingly) geo-location or GPS coordinates. Digital/GIS maps (aerial, cadastral, or GIS-derived) are accepted and often preferred; some certifiers use KML/KMZ or GIS for verification and Internal Control Systems. Field history is linked to mapped parcels.
• FSMA Food Traceability Rule (US) Traceability Plan — Explicit requirement for a farm map of growing areas for listed foods, including the location and name of each field (or aquaculture container) plus geographic coordinates and any other identifying information.
• GLOBALG.A.P. Integrated Farm Assurance (IFA) and related checklists — Farm/field maps and location data for risk assessments, traceability, and audits; spatial elements support sustainability add-ons and compliance verification.
• Conservation compliance (e.g., USDA HELC/WC, Form AD-1026) — Relies on GIS layers for Highly Erodible Land and wetland determinations; maps and spatial data support certifications.
• Related records — Precision agriculture logs, input application maps, and audit trails often generated or stored in GIS-enabled farm management systems.

GIS/digital mapping is increasingly required or strongly encouraged for organic integrity, traceability (lot-to-field linking), and regulatory verification. Tools like GPS-enabled mobile apps and platforms that produce KML/shapefiles are common.

Notes

• Exact GIS requirements (formats, coordinate systems, metadata) are jurisdiction- and agency-specific and evolve with digital submission rules.
• Many other documents (e.g., general EIAs, safety plans) can incorporate GIS but do not always mandate it.
• In both sectors, spatial data supports audits, mass-balance checks, environmental monitoring, and supply-chain transparency.

For the most current details, check the relevant regulatory body or certification scheme in your jurisdiction, as digital/GIS standards are being strengthened.

[ngoiyaeric]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Extend (do not replace) the existing two-agent report pipeline by adding a report domain/type parameter threaded from the UI through submit() into generateReportContext.
• Add a dedicated, domain-parameterized compliance synthesis agent that produces structured, standards-aligned output for mining and agriculture, grounded in existing chat context, sensor-fusion findings, and drawn AOI geometries.
• Render a new "Regulatory Compliance Assessment" section plus a GIS-enriched spatial appendix in the report template, and provide KML/GeoJSON exports of mapped AOIs to satisfy GIS-format expectations.
• Default general reports remain unchanged, and jurisdiction-specific GIS nuances are surfaced as flagged assumptions rather than hard regulatory assertions.

Design Choices

Design Choice 1: How should mining/agriculture compliance domain knowledge be injected into report generation?

Options Considered:

1. Inject compliance knowledge via the user's custom system prompt (users.systemPrompt).
2. Add a dedicated compliance report agent + schema, selected by a report domain/type parameter, running alongside the existing report agents.

Chosen Option: 2

Rationale: The codebase offers two hooks: the per-user users.systemPrompt override (a full replacement of the researcher prompt) or the report-agent pipeline. The system-prompt override is global-per-user, wholesale (loses tool-routing rules), and free-text (cannot produce structured, standard-aligned output), making it unsuitable for deterministic compliance sections. A dedicated agent keyed by report domain produces structured, standard-aligned compliance content without sacrificing the researcher's tool-routing behavior, and slots cleanly into the existing report pipeline and template.

Design Choice 2: What GIS-compatible export format should accompany the compliance report?

Options Considered:

1. Generate ESRI Shapefiles.
2. Generate KML/KMZ and GeoJSON from drawn AOIs/geometries.

Chosen Option: 2

Rationale: The ticket stresses GIS-compatible formats (shapefiles, KML/KMZ). Shapefiles are binary multi-file archives requiring heavier libraries; drawn features are already WGS84 GeoJSON. KML and GeoJSON are text-based, generated client-side from existing drawnFeatures, satisfy the "GIS-compatible format" requirement, and are the formats certifiers/agencies most commonly accept for verification.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Introduce a report domain/type model and selection workflow

Establish the concept of a "report domain" (general / mining exploration / agriculture) with optional document-type subtypes (e.g., JORC/NI 43-101 technical report, reclamation/disturbance report; organic certification farm map, FSMA traceability plan). The goal is to let the user choose what kind of compliance document they are producing and thread that choice end-to-end through the report pipeline, while keeping the current generic report as the default so existing behavior is unchanged.

Task 1: Define the report domain taxonomy and shared types

Create a single source of truth describing the supported report domains, their document subtypes, and the standards each references.

• Add a new config/module (e.g., under lib/schema/ or lib/config/) defining a ReportDomain union ('general' | 'mining' | 'agriculture') and, per domain, a list of document subtypes with human-readable labels and the associated standards (JORC, NI 43-101, S-K 1300, PERC; USDA NOP, EU 2018/848, FSMA, GLOBALG.A.P., HELC/WC).
• Define a Zod schema for validating the incoming reportType/domain parameter, following the existing lib/schema/* pattern.
• Export TypeScript types to be reused by the server action, the report agents, and the template props.

Task 2: Add report-type selection to the report trigger UI

Give the user a way to pick a domain/subtype before generating the report.

• Update components/download-report-button.tsx to present a lightweight selector (dropdown/menu) driven by the taxonomy from Task 1.1; default selection is general to preserve current behavior.
• Append the chosen reportType (and optional subtype) to the FormData sent to actions.submit(), alongside the existing action and messages.
• Pass the selected domain into <ReportTemplate> as a new prop so the template can conditionally render domain-specific sections.

Task 3: Thread the report domain through the server action and context builder

Propagate the selected domain from the request into the report-generation logic.

• Update the generate_report_context branch of submit() in app/actions.tsx to read and validate the new reportType field and forward it to generateReportContext.
• Update generateReportContext in lib/actions/chat.ts to accept an optional reportType/domain argument and, when it is a compliance domain, invoke the new compliance agent (Phase 2) in addition to the existing executive-summary/strategic-synthesis agents, extending the returned object with a new complianceOutput field (kept undefined for general).

🤖 Prompt for AI agents

Implement the report domain/type taxonomy and thread it end-to-end from the
report trigger UI to the report context builder, keeping `general` as the
default and preserving existing behavior when no compliance domain is selected.

- Create a new config/schema module (e.g., under `lib/schema/` or `lib/config/`)
defining a `ReportDomain` union type (`'general' | 'mining' | 'agriculture'`),
per-domain document subtypes with human-readable labels, and the associated
standards (JORC, NI 43-101, S-K 1300, PERC for mining; USDA NOP, EU 2018/848,
FSMA, GLOBALG.A.P., HELC/WC for agriculture). Define a Zod schema validating the
`reportType`/`domain` parameter, following the existing `lib/schema/*` pattern,
and export TypeScript types for reuse by the server action, report agents, and
template props.
- Update `components/download-report-button.tsx` to add a lightweight selector
(dropdown/menu) driven by this taxonomy, defaulting to `general`. Append the
chosen `reportType` (and optional subtype) to the `FormData` sent to
`actions.submit()` alongside the existing `action` and `messages` fields. Pass
the selected domain as a new prop into `<ReportTemplate>`.
- Update the `generate_report_context` branch of `submit()` in `app/actions.tsx`
to read and validate the new `reportType` field and forward it to
`generateReportContext`.
- Update `generateReportContext` in `lib/actions/chat.ts` to accept an optional
`reportType`/domain argument. When the domain is a compliance domain
(mining/agriculture), it should also invoke the compliance agent (built in a
later phase) alongside the existing `executiveSummaryAgent` and
`strategicSynthesisAgent`, and extend the returned object with a new
`complianceOutput` field, which stays `undefined` for `general`.

Phase 2: Add a domain-aware compliance synthesis agent

Introduce structured, standards-aligned compliance content generation. The agent consumes the same conversation transcript, sensor-fusion findings, and drawn AOI geometries already available to the report pipeline, but produces a compliance-oriented, structured assessment framed around the selected domain's regulatory expectations and spatial-data requirements (coordinates, boundaries, datum/projection, disturbance/field areas, traceability).

Task 1: Implement the compliance report agent

Create a new report agent parallel to the existing two, selecting a domain-specific prompt and output structure.

• Create a new module in lib/agents/report/ (e.g., compliance-synthesis.ts) exposing an agent function that accepts the domain, subtype, active messages, sensor-fusion findings, and drawn-feature/spatial context.
• Use generateText (matching the existing report-agent pattern) with a domain-specialized system prompt: for mining, frame output around tenure boundaries, drill/sample/disturbance/reclamation spatial data, and CRIRSCO-aligned disclosure expectations; for agriculture, frame around field/parcel boundaries, buffer zones, geo-coordinates, and traceability (lot-to-field) expectations.
• Return a structured complianceOutput (parsed JSON) with clearly named subsections (e.g., regulatory framework references, spatial-data summary/metadata, key compliance observations, gaps/recommended actions), following the JSON-parsing-with-fallback approach already used by executive-summary.ts/strategic-synthesis.ts.
• Explicitly note in the prompt that jurisdiction-specific GIS formats/coordinate systems/metadata vary, so the output should flag assumptions rather than assert regulatory certainty.

Task 2: Derive spatial-metadata context for the agent and template

Assemble the coordinate/boundary/measurement details the compliance domains require, from data already present in the app.

• Add a helper (co-located with the compliance agent or in lib/actions/chat.ts) that transforms drawnFeatures (GeoJSON geometries + measurements from map-data-context) into a normalized spatial summary: feature identity, geometry type, area/length, bounding coordinates, and datum/projection labeling (WGS84 / EPSG:4326, matching Mapbox GL output).
• Feed this spatial summary into the compliance agent (Task 2.1) and also surface it to the template (Phase 3) so the rendered appendix and the AI narrative are consistent.

🤖 Prompt for AI agents

Build a new domain-aware compliance synthesis agent that mirrors the existing
report-agent pattern, and a spatial-metadata helper that feeds both the agent
and the template.

- Create a new module in `lib/agents/report/` (e.g., `compliance-synthesis.ts`)
exposing an agent function accepting the domain, subtype, active messages,
sensor-fusion findings, and drawn-feature/spatial context.
- Use `generateText` (matching the existing
`executive-summary.ts`/`strategic-synthesis.ts` pattern) with a
domain-specialized system prompt: for mining, frame around tenure boundaries,
drill/sample/disturbance/reclamation spatial data, and CRIRSCO-aligned
disclosure expectations; for agriculture, frame around field/parcel boundaries,
buffer zones, geo-coordinates, and traceability (lot-to-field) expectations.
- Return a structured `complianceOutput` (parsed JSON) with clearly named
subsections: regulatory framework references, spatial-data summary/metadata, key
compliance observations, and gaps/recommended actions. Follow the same
JSON-parsing-with-fallback approach already used by the existing report agents
so malformed responses never break downstream rendering.
- In the prompt, explicitly instruct the model that jurisdiction-specific GIS
formats/coordinate systems/metadata vary, and that it should flag assumptions
rather than assert regulatory certainty.
- Add a helper (co-located with the compliance agent or in
`lib/actions/chat.ts`) that transforms `drawnFeatures` (GeoJSON geometries +
measurements from `map-data-context`) into a normalized spatial summary
containing feature identity, geometry type, area/length, bounding coordinates,
and datum/projection labeling (WGS84 / EPSG:4326, matching Mapbox GL output).
- Feed this spatial summary into the compliance agent as context, and also make
it available to the report template (for the spatial appendix) so the AI
narrative and rendered appendix stay consistent.

Phase 3: Render compliance sections and enable GIS-compatible export

Extend the report document to display the compliance assessment and a GIS-oriented spatial appendix, and give the user GIS-compatible file exports of the mapped AOIs so the report package matches what mining/agriculture submissions expect.

Task 1: Add compliance sections to the report template

Render the new domain-specific content when a compliance domain is selected.

• Update components/report-template.tsx ReportTemplateProps to accept the selected reportType/domain, complianceOutput, and the spatial summary from Task 2.2.
• Add a new numbered "Regulatory Compliance Assessment" section (rendered only when complianceOutput is present), following the existing "render only if prop truthy" and data-pdf-nosplit conventions; render its structured subsections (framework references, observations, gaps/recommended actions) via the existing ReactMarkdown pattern.
• Enhance the Quantitative/Spatial Appendix to include GIS-relevant columns (coordinates/bounding box, datum/projection, computed area/length) driven by the spatial summary, so the appendix reads as a compliance-grade spatial data table.
• Adjust the hardcoded section numbering to accommodate the inserted section (or convert the numbering to a small ordered list to insert cleanly).

Task 2: Add KML/GeoJSON export of drawn AOIs

Provide GIS-compatible spatial file outputs alongside the PDF.

• Add a utility (near lib/utils/report-generator.ts) that converts drawnFeatures GeoJSON into KML and standalone GeoJSON files (WGS84), with feature names/labels derived from the compliance context.
• Wire an export affordance into components/download-report-button.tsx (available for compliance domains) that triggers download of the KML/GeoJSON in addition to the generated PDF.
• Keep this purely client-side/text-based to avoid new heavy dependencies.

🤖 Prompt for AI agents

Extend the report template to render the new compliance content and spatial
appendix enhancements, and add client-side GIS export utilities for drawn AOIs.

- Update `components/report-template.tsx` `ReportTemplateProps` to accept the
selected `reportType`/domain, `complianceOutput`, and the spatial summary
produced in Phase 2.
- Add a new numbered "Regulatory Compliance Assessment" section that renders
only when `complianceOutput` is present, following the existing "render only if
prop truthy" and `data-pdf-nosplit` conventions used elsewhere in the template.
Render its structured subsections (framework references, observations,
gaps/recommended actions) via the existing ReactMarkdown pattern.
- Enhance the existing Quantitative/Spatial Appendix to include GIS-relevant
columns (coordinates/bounding box, datum/projection, computed area/length)
driven by the spatial summary, making the appendix read as a compliance-grade
spatial data table.
- Adjust the hardcoded section numbering (sections `00`–`03`) to accommodate the
newly inserted section, or convert the numbering scheme to a small ordered list
so sections can be inserted cleanly.
- Add a new utility near `lib/utils/report-generator.ts` that converts
`drawnFeatures` GeoJSON into KML and standalone GeoJSON files (WGS84), with
feature names/labels derived from the compliance context.
- Wire an export affordance into `components/download-report-button.tsx`,
available for compliance domains, that triggers a download of the KML/GeoJSON
files in addition to the generated PDF. Keep this implementation purely
client-side/text-based to avoid introducing new heavy dependencies (e.g., avoid
shapefile libraries).

Research

QCX-Terra is a Next.js + Vercel AI SDK conversational geospatial assistant. Chat orchestration runs through the submit() server action in app/actions.tsx, which branches on a FormData action string. Report export is an on-demand, two-agent pipeline: download-report-button.tsx captures a Mapbox snapshot and chat history, calls submit(action='generate_report_context'), which invokes generateReportContext(messages) in lib/actions/chat.ts. That function runs executiveSummaryAgent and strategicSynthesisAgent (lib/agents/report/*) and returns { title, summary, strategicOutput }, which are rendered by components/report-template.tsx (fixed, hardcoded sections 00–03) and rasterized to PDF via lib/utils/report-generator.ts. Map-drawn AOIs/geometries flow from components/map/map-data-context.tsx as drawnFeatures (GeoJSON + measurement). There is no existing report-type/domain concept, and no mining/agriculture/compliance logic anywhere in the codebase — this is greenfield domain work that extends the existing report pipeline rather than replacing it.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the report domain/type taxonomy and thread it end-to-end from the
report trigger UI to the report context builder, keeping `general` as the
default and preserving existing behavior when no compliance domain is selected.

- Create a new config/schema module (e.g., under `lib/schema/` or `lib/config/`)
defining a `ReportDomain` union type (`'general' | 'mining' | 'agriculture'`),
per-domain document subtypes with human-readable labels, and the associated
standards (JORC, NI 43-101, S-K 1300, PERC for mining; USDA NOP, EU 2018/848,
FSMA, GLOBALG.A.P., HELC/WC for agriculture). Define a Zod schema validating the
`reportType`/`domain` parameter, following the existing `lib/schema/*` pattern,
and export TypeScript types for reuse by the server action, report agents, and
template props.
- Update `components/download-report-button.tsx` to add a lightweight selector
(dropdown/menu) driven by this taxonomy, defaulting to `general`. Append the
chosen `reportType` (and optional subtype) to the `FormData` sent to
`actions.submit()` alongside the existing `action` and `messages` fields. Pass
the selected domain as a new prop into `<ReportTemplate>`.
- Update the `generate_report_context` branch of `submit()` in `app/actions.tsx`
to read and validate the new `reportType` field and forward it to
`generateReportContext`.
- Update `generateReportContext` in `lib/actions/chat.ts` to accept an optional
`reportType`/domain argument. When the domain is a compliance domain
(mining/agriculture), it should also invoke the compliance agent (built in a
later phase) alongside the existing `executiveSummaryAgent` and
`strategicSynthesisAgent`, and extend the returned object with a new
`complianceOutput` field, which stays `undefined` for `general`.
===============================================================================

Task: 2

Build a new domain-aware compliance synthesis agent that mirrors the existing
report-agent pattern, and a spatial-metadata helper that feeds both the agent
and the template.

- Create a new module in `lib/agents/report/` (e.g., `compliance-synthesis.ts`)
exposing an agent function accepting the domain, subtype, active messages,
sensor-fusion findings, and drawn-feature/spatial context.
- Use `generateText` (matching the existing
`executive-summary.ts`/`strategic-synthesis.ts` pattern) with a
domain-specialized system prompt: for mining, frame around tenure boundaries,
drill/sample/disturbance/reclamation spatial data, and CRIRSCO-aligned
disclosure expectations; for agriculture, frame around field/parcel boundaries,
buffer zones, geo-coordinates, and traceability (lot-to-field) expectations.
- Return a structured `complianceOutput` (parsed JSON) with clearly named
subsections: regulatory framework references, spatial-data summary/metadata, key
compliance observations, and gaps/recommended actions. Follow the same
JSON-parsing-with-fallback approach already used by the existing report agents
so malformed responses never break downstream rendering.
- In the prompt, explicitly instruct the model that jurisdiction-specific GIS
formats/coordinate systems/metadata vary, and that it should flag assumptions
rather than assert regulatory certainty.
- Add a helper (co-located with the compliance agent or in
`lib/actions/chat.ts`) that transforms `drawnFeatures` (GeoJSON geometries +
measurements from `map-data-context`) into a normalized spatial summary
containing feature identity, geometry type, area/length, bounding coordinates,
and datum/projection labeling (WGS84 / EPSG:4326, matching Mapbox GL output).
- Feed this spatial summary into the compliance agent as context, and also make
it available to the report template (for the spatial appendix) so the AI
narrative and rendered appendix stay consistent.
===============================================================================

Task: 3

Extend the report template to render the new compliance content and spatial
appendix enhancements, and add client-side GIS export utilities for drawn AOIs.

- Update `components/report-template.tsx` `ReportTemplateProps` to accept the
selected `reportType`/domain, `complianceOutput`, and the spatial summary
produced in Phase 2.
- Add a new numbered "Regulatory Compliance Assessment" section that renders
only when `complianceOutput` is present, following the existing "render only if
prop truthy" and `data-pdf-nosplit` conventions used elsewhere in the template.
Render its structured subsections (framework references, observations,
gaps/recommended actions) via the existing ReactMarkdown pattern.
- Enhance the existing Quantitative/Spatial Appendix to include GIS-relevant
columns (coordinates/bounding box, datum/projection, computed area/length)
driven by the spatial summary, making the appendix read as a compliance-grade
spatial data table.
- Adjust the hardcoded section numbering (sections `00`–`03`) to accommodate the
newly inserted section, or convert the numbering scheme to a small ordered list
so sections can be inserted cleanly.
- Add a new utility near `lib/utils/report-generator.ts` that converts
`drawnFeatures` GeoJSON into KML and standalone GeoJSON files (WGS84), with
feature names/labels derived from the compliance context.
- Wire an export affordance into `components/download-report-button.tsx`,
available for compliance domains, that triggers a download of the KML/GeoJSON
files in addition to the generated PDF. Keep this implementation purely
client-side/text-based to avoid introducing new heavy dependencies (e.g., avoid
shapefile libraries).

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!