feat: enhance documentation with metadata, descriptions, and tags for improved navigation and clarity

gmarupilla · gmarupilla · commit 0af30a1eeaa5 · 2026-02-20T08:03:22.000-06:00
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
@@ -1,3 +1,13 @@
+---
+title: Development Guide
+description: Environment setup, project structure, testing, code style, and step-by-step guide for contributing to TerraFlow.
+icon: material/wrench
+tags:
+  - Development
+  - Contributing
+  - Reference
+---
+
 # TerraFlow Development Guide
 
 This guide helps you set up a development environment, understand the codebase, and contribute to TerraFlow.
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
@@ -1,3 +1,12 @@
+---
+title: Roadmap
+description: Strategic direction for TerraFlow — completed tracks, planned v1.0 features, and future production capabilities.
+icon: material/road-variant
+tags:
+  - Development
+  - Reference
+---
+
 # TerraFlow Feature Roadmap
 
 Last Updated: 2026-02-06
diff --git a/docs/api/climate.md b/docs/api/climate.md
@@ -1,3 +1,12 @@
+---
+title: Climate API
+description: API reference for terraflow.climate — ClimateInterpolator, spatial and index strategies, and per-cell value assignment.
+icon: material/weather-partly-cloudy
+tags:
+  - API
+  - Reference
+---
+
 # terraflow.climate
 
 The climate module provides spatial interpolation and index-based matching for aligning climate observations to raster cells.
diff --git a/docs/api/core.md b/docs/api/core.md
@@ -1,3 +1,12 @@
+---
+title: Core API
+description: API reference for terraflow.config, terraflow.pipeline, and terraflow.model — configuration schema, pipeline orchestration, and suitability scoring.
+icon: material/cog
+tags:
+  - API
+  - Reference
+---
+
 # terraflow.core
 
 The core modules define the configuration schema and the end-to-end pipeline.
diff --git a/docs/api/ingest.md b/docs/api/ingest.md
@@ -1,3 +1,12 @@
+---
+title: Ingest API
+description: API reference for terraflow.ingest — raster and climate CSV loading, file validation, and IO helpers.
+icon: material/database-import
+tags:
+  - API
+  - Reference
+---
+
 # terraflow.ingest
 
 The ingest module contains IO helpers for loading raster and climate inputs.
diff --git a/docs/architecture/adr-001-band-selection.md b/docs/architecture/adr-001-band-selection.md
@@ -1,3 +1,12 @@
+---
+title: "ADR-001: Single-Band Raster Processing"
+description: Decision record for processing only Band 1 from input rasters — rationale, consequences, and future alternatives.
+icon: material/numeric-1-box-outline
+tags:
+  - Architecture
+  - ADR
+---
+
 # ADR-001: Single-Band Raster Processing
 
 **Date**: 2026-02-06  
diff --git a/docs/architecture/adr-002-bbox-roi.md b/docs/architecture/adr-002-bbox-roi.md
@@ -1,3 +1,12 @@
+---
+title: "ADR-002: Bounding Box Only ROI Support"
+description: Decision record for restricting ROI to bounding boxes — performance rationale, consequences, and polygon roadmap.
+icon: material/numeric-2-box-outline
+tags:
+  - Architecture
+  - ADR
+---
+
 # ADR-002: Bounding Box Only ROI Support
 
 **Date**: 2026-02-06  
diff --git a/docs/architecture/adr-003-climate-interpolation.md b/docs/architecture/adr-003-climate-interpolation.md
@@ -1,3 +1,12 @@
+---
+title: "ADR-003: Climate Data Interpolation Strategies"
+description: Decision record for per-cell spatial interpolation — spatial vs index strategies, scipy.griddata, and fallback handling.
+icon: material/numeric-3-box-outline
+tags:
+  - Architecture
+  - ADR
+---
+
 # ADR-003: Climate Data Interpolation Strategies
 
 **Status**: Accepted  
diff --git a/docs/architecture/adr-004-crs-reprojection.md b/docs/architecture/adr-004-crs-reprojection.md
@@ -1,3 +1,12 @@
+---
+title: "ADR-004: CRS Reprojection for ROI and Output Coordinates"
+description: Decision record for pyproj-based ROI reprojection and guaranteed WGS 84 output coordinates — fixes TERRA-010 and TERRA-011.
+icon: material/numeric-4-box-outline
+tags:
+  - Architecture
+  - ADR
+---
+
 # ADR-004: CRS Reprojection for ROI and Output Coordinates
 
 **Status**: Accepted
diff --git a/docs/architecture/artifacts.md b/docs/architecture/artifacts.md
@@ -1,3 +1,13 @@
+---
+title: Output Artifact Contract
+description: The guaranteed output files written by every TerraFlow run — results.csv, manifest.json, and report.json schemas.
+icon: material/file-check-outline
+tags:
+  - Architecture
+  - Reference
+  - Outputs
+---
+
 # Artifact Contract
 
 Each run writes a consistent set of artifacts under:
diff --git a/docs/architecture/boundaries.md b/docs/architecture/boundaries.md
@@ -1,3 +1,12 @@
+---
+title: Architecture Boundaries
+description: The ingest/core layer split — why separating data loading from pipeline logic keeps TerraFlow deterministic and auditable.
+icon: material/border-all
+tags:
+  - Architecture
+  - Reference
+---
+
 # Architecture Boundaries
 
 TerraFlow splits the pipeline into two primary layers:
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
@@ -1,3 +1,12 @@
+---
+title: Architecture Overview
+description: Module boundaries, data flow, and reproducibility model for TerraFlow's geospatial pipeline.
+icon: material/sitemap
+tags:
+  - Architecture
+  - Reference
+---
+
 # TerraFlow Overview
 
 TerraFlow is a reproducible geospatial modeling framework that turns local geospatial inputs into
diff --git a/docs/architecture/run-identity.md b/docs/architecture/run-identity.md
@@ -1,3 +1,13 @@
+---
+title: Run Identity & Fingerprinting
+description: How TerraFlow computes deterministic run fingerprints from config, ROI, and input file hashes to guarantee reproducibility.
+icon: material/fingerprint
+tags:
+  - Architecture
+  - Reproducibility
+  - Reference
+---
+
 # Run Identity
 
 Every pipeline execution is identified by a deterministic `run_fingerprint` computed as:
diff --git a/docs/cli/usage.md b/docs/cli/usage.md
@@ -1,3 +1,12 @@
+---
+title: CLI Usage
+description: How to run TerraFlow from the command line — flags, config resolution, and output locations.
+icon: material/console
+tags:
+  - CLI
+  - Reference
+---
+
 # CLI Usage
 
 TerraFlow exposes a lightweight CLI for running the pipeline.
diff --git a/docs/config/examples.md b/docs/config/examples.md
@@ -1,3 +1,12 @@
+---
+title: Configuration Examples
+description: Ready-to-use TerraFlow YAML configuration templates for common scenarios — WGS84 rasters, projected CRS, spatial and index climate strategies.
+icon: material/file-document-multiple-outline
+tags:
+  - Configuration
+  - Examples
+---
+
 # Configuration Examples
 
 Below is a complete example configuration aligned with v0.2.0 with spatial climate interpolation.
diff --git a/docs/config/schema.md b/docs/config/schema.md
@@ -1,3 +1,12 @@
+---
+title: Configuration Schema
+description: Complete YAML configuration reference for TerraFlow — ROI, model parameters, climate strategies, and CRS options.
+icon: material/file-cog-outline
+tags:
+  - Configuration
+  - Reference
+---
+
 # Configuration Schema
 
 TerraFlow v0.2.0 uses a single YAML configuration file that maps to the `PipelineConfig` model.
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,3 +1,12 @@
+---
+title: Contributing Guidelines
+description: How to set up locally, run tests and linting, preview docs, and submit a pull request to TerraFlow.
+icon: material/source-pull
+tags:
+  - Development
+  - Contributing
+---
+
 # Contributing
 
 Thanks for helping improve TerraFlow! Here are the basics for v0.2.0+.
diff --git a/docs/field-guide.md b/docs/field-guide.md
@@ -1,3 +1,13 @@
+---
+title: Field Guide — Understanding Results
+description: A plain-English guide to reading TerraFlow outputs. For land managers, agricultural consultants, and extension agents who work with results without writing code.
+icon: material/map-marker-outline
+tags:
+  - Non-Technical
+  - Results
+  - Land Management
+---
+
 # Field Guide — Understanding TerraFlow Results
 
 *For land managers, agricultural consultants, extension agents, and anyone who uses the outputs without writing the code.*
diff --git a/docs/index.md b/docs/index.md
@@ -1,3 +1,9 @@
+---
+title: TerraFlow
+description: Reproducible geospatial modeling for agricultural suitability analysis — config-driven, fingerprinted, and spatially aware.
+icon: material/sprout
+---
+
 # TerraFlow Documentation
 
 TerraFlow is a reproducible geospatial tool for agricultural suitability modeling — it takes a land-cover map, climate data, and a configuration file, and produces a scored, location-stamped results table.
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -1,3 +1,12 @@
+---
+title: TerraFlow in 10 Minutes
+description: Learn what TerraFlow does, how the pipeline works, and run your first suitability analysis — all in under 10 minutes.
+icon: material/clock-fast
+tags:
+  - Getting Started
+  - Tutorial
+---
+
 # TerraFlow in 10 Minutes
 
 Everything you need to go from zero to a working suitability map — what it is, why it exists, how it works, and a live run you can follow along with.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -41,6 +41,7 @@ markdown_extensions:
 
 plugins:
   - search
+  - tags
   - mermaid2
   - mkdocstrings:
       handlers:
