Repository map¶

Use this page to decide which file to read or modify. The repository contains runtime code, educational material, generated evidence, and historical files; their presence in the same checkout does not give them the same role.

Sources of truth¶

When documentation and an old exploratory file disagree, use this order:

src/spectralbridge/ — current installed behavior;
tests/ — executable contracts and regression cases;
docs/ — current user and developer documentation;
examples/ and docs/vignettes/notebooks/ — editable adapters over the current package;
archive/, provenance/ and deprecated/ — historical research and provenance; tested transfer interfaces retain stable root paths.

Where to begin¶

You want to understand…	Read first	Then inspect
Complete NEON orchestration	`examples/run_neon_pipeline.py`	`src/spectralbridge/pipelines/pipeline.py`
Drone orchestration	`examples/run_drone_pipeline.py`	`src/spectralbridge/pipelines/drone.py`
Cross-run bulk analysis	The bulk-analysis vignette	`src/spectralbridge/bulk/` and `src/spectralbridge/pipelines/bulk.py`
Canonical filenames	`docs/naming-conventions.md`	`src/spectralbridge/paths.py` and `src/spectralbridge/utils/naming.py`
Topographic/BRDF correction	`docs/brdf_topo_algorithm.md`	`src/spectralbridge/corrections.py` and `src/spectralbridge/brdf_topo.py`
Sensor convolution	The harmonization vignette	`src/spectralbridge/standard_resample.py` and packaged band JSON
Parquet and polygon products	The analysis-table and polygon vignettes	`src/spectralbridge/parquet_export.py`, `merge_duckdb.py`, and `polygons.py`
QA evidence	The QA vignette and validation pages	`qa_plots.py`, `qa_metrics.py`, and QA tests
JSON parameters	The JSON catalog	The loader named in that catalog
A custom correction	The custom-correction hook	Stage functions in `pipelines/pipeline.py`

What each top-level area means¶

Area	Label	Guidance
`src/spectralbridge/`	Runtime	Installed package; changes require focused tests
`tests/`	Contracts	Best place to verify what the package promises
`examples/`	Copyable runners	Small scripts and JSON configs for local or container use
`docs/vignettes/notebooks/`	Interactive runners	Current ordered notebook set, including independent bulk analysis, with processing disabled until configured
`scripts/`	Operations and maintenance	Read `scripts/README.md`; not every script is a user entry point
`validation/`	Evidence	Separates campaign plans from generated observations
`data/`, `Datasets/`	Historical study inputs	Retained for notebook compatibility; installed code uses `src/spectralbridge/data/`
`paper/`	Publication	Canonical manuscript/SI Markdown, BibTeX and figures; archive/ and generated/ separate snapshots/derivatives
`archive/`	Research history	Campaign notebooks, polygon layers and supplied bulk evidence; immutable snapshots
`provenance/`	Attribution and history	Prompt history, HyTools record, forensic audits and migration ledger
`deprecated/`	Provenance	Do not use as the basis for new code

The root Drone_processing.ipynb and Raster_processing.ipynb are retained active research notebooks. New users should begin with the smaller ordered notebook vignettes, which expose the same current entry points with clearer stage boundaries.

How to verify code yourself¶

Start narrow and expand only when the change crosses contracts:

python examples/run_neon_pipeline.py --check
pytest -q tests/test_example_entrypoints.py
pytest -q tests/test_pipeline_convolution.py
python scripts/check_docs_links.py

For scientific parameter changes, also run the coefficient, correction, or convolution tests named in the JSON catalog and inspect the resulting QA, not only the test exit status.

Compatibility interfaces¶

FEATURE_REQUESTS.md and HYTOOLS_PROVENANCE.md remain at root because agents, release/attribution tooling and citations rely on them. PROMPT_LOG.md points to its canonical provenance location. Root polygon symlinks preserve active/historical notebook paths. The root gocmd is a portable launcher; install the official platform-specific client as described in container/remote guidance. Root transfer helpers are retained because tests and external callers import them. New users should use the supported package workflows, not historical scripts.

The cleanup record contains the full artifact inventory, risk decisions and checksummed move ledger.