# Green-Guides Sources Status

Upstream BMP manual references:

- `2026`: https://dep.nj.gov/stormwater/stormwater-management/bmp-manual/nj-stormwater-best-management-practices-manual-2026/
- `2023`: https://dep.nj.gov/stormwater/stormwater-management/bmp-manual/nj-stormwater-best-management-practices-manual-2023/

## Current Canon

For this repository, the authoritative maintained source corpus lives under:

- `docs/Sources`

That means:

- `docs/Sources/*/Markdown/*.md` is the working source-of-truth text corpus
- `docs/Sources/BMP_*/*.pdf` and `docs/Sources/NJAC_*/*.pdf` are the paired binary source documents
- `docs/Sources/*/raw/` is the repo-local OCR evidence backend
- `docs/Sources/citations/*` is the canonical citations and registry layer

External shares, backups, or synced copies may exist, but they are not the live authority for this repo unless they are explicitly re-imported into `docs/Sources`.

## Current Layout

Managed source families:

- `BMP_2023`
- `BMP_2026`
- `NJAC_2023`
- `NJAC_2026`
- `citations`

Within each BMP or NJAC family:

- PDFs live at the family root
- extracted markdown lives under `Markdown/`
- raw OCR evidence lives under `raw/`

Examples:

- `BMP_2023/2023_BMP_1_Impacts_of_Development_on_Runoff.pdf`
- `BMP_2023/Markdown/2023_BMP_1_Impacts_of_Development_on_Runoff.md`
- `BMP_2023/raw/2023_BMP_1_Impacts_of_Development_on_Runoff/manifest.json`

## Portable Path Contract

Markdown frontmatter uses file-relative `source_pdf` paths:

```yaml
source_pdf: ../2023_BMP_1_Impacts_of_Development_on_Runoff.pdf
```

Registry and generated citations artifacts use `Sources`-root-relative paths:

- `BMP_2023/2023_BMP_1_Impacts_of_Development_on_Runoff.pdf`
- `BMP_2023/Markdown/2023_BMP_1_Impacts_of_Development_on_Runoff.md`
- `BMP_2023/raw/2023_BMP_1_Impacts_of_Development_on_Runoff/manifest.json`

This is intentional:

- markdown frontmatter stays self-referential from the markdown file
- registry and citations paths stay stable relative to the published `Sources/` root
- no managed contract should emit obsolete `*_OCR` or `*_EXTRACTED` family-directory names

## Current Generated Artifacts

Authoritative maintained files under `Sources/citations/`:

- `source_document_registry.json`
- `bmp_crosswalk.json`
- `bmp_crosswalk.md`
- `njac_section_index.json`
- `raw_index.json`
- `report_claims.json`
- `report_claims.md`
- `frontmatter_template.md`
- `README.md`

Current status:

- registry paths are normalized to the portable family layout
- citation artifacts are maintained only under `docs/Sources/citations`
- the former `docs/assets/tools/citations` mirror has been retired

## Citations Contract

`Sources/citations/` is the only canonical citations location in this repo.

Use it for:

- source identity and path joins
- raw-evidence indexing
- BMP crosswalk maintenance
- report claim tracing
- frontmatter contract reference

Do not treat `assets/tools/citations` as authored storage. That mirror was removed so citation maintenance stays single-source.

## Raw Evidence Notes

`Sources/*/raw/` contains the repo-local OCR evidence bundles used to support QA and citation maintenance.

Important rules:

- `manifest.json` is the preferred metadata entrypoint
- `response.json` is the deep evidence payload
- `pages/` contains decoded page images when available
- raw evidence should override stale prose summaries when conflicts appear

## Source Identity Rules

- BMP and NJAC source documents should retain stable registry-style `src-*` identities
- PDFs and Markdown twins should share the same source identity
- broad browse tags remain semantic and structural, not machine-path-derived
- path fields in registries and manifests should remain relative to the `Sources/` root

## Deprecated Assumptions

These are obsolete and should not be reused:

- `F:\Paperless-lib`
- `\\TRUENAS\media\Paperless-lib`
- `\\TRUENAS\knowledge\Curated\Paperless-lib\Engineering\Sources` as the live repo authority
- `assets/tools/citations` as a maintained citations mirror
- `Sources/2023_BMP_OCR/...`
- `Sources/2026_BMP_OCR/...`
- `Sources/2023_BMP_EXTRACTED/...`
- `Sources/2026_BMP_EXTRACTED/...`
- `Sources/2023_NJAC_OCR/...`
- `Sources/2026_NJAC_OCR/...`
- `Sources/2023_NJAC_EXTRACTED/...`
- `Sources/2026_NJAC_EXTRACTED/...`

## Practical Rule

If you need to regenerate or validate the corpus:

1. update files directly under `docs/Sources`
2. rebuild or refresh the citations artifacts under `docs/Sources/citations`
3. validate path consistency against the `Sources/`-root-relative contract
4. run the normal site build so published `site/Sources/...` output stays in parity

As of `2026-04-09`, this note reflects the live repo-local source-corpus contract.
