# Using the Sources Folder

This folder is the source library for Green Guides.

If you want to know where a report, table, crosswalk, or engineering statement came from, start here.

## What `/Sources` Is For

`docs/Sources` holds the repo's maintained source corpus:

- the original BMP and NJAC PDFs
- the extracted Markdown versions used for reading and comparison
- the raw OCR evidence bundles used for QA and traceability
- the citations and registry files that connect authored content back to source material

In short:

- reports in `docs/reports` are authored outputs
- files in `docs/Sources` are the evidence and reference base those outputs should come from

## What's Inside

Top-level folders:

- `BMP_2023`
  NJ Stormwater BMP Manual 2023 source family.
- `BMP_2026`
  NJ Stormwater BMP Manual 2026 source family.
- `NJAC_2023`
  2023 NJ stormwater rule source family.
- `NJAC_2026`
  2026 NJ stormwater rule source family.
- `citations`
  Registry, crosswalk, report-claim, and source-index artifacts.

Top-level docs:

- `Entry.md`
  This human-readable introduction.
- `sources-readme.md`
  The more technical operating contract for paths, source layout, and citation maintenance.

## How Each Source Family Works

Inside each BMP or NJAC family, the structure is consistent:

- PDF files at the family root
  These are the paired source documents.
- `Markdown/`
  These are the extracted text versions used for reading, comparison, and citation work.
- `raw/`
  These are the OCR evidence bundles used for QA and traceability.

Example:

```text
BMP_2023/
  2023_BMP_10_1_Bioretention_Systems.pdf
  Markdown/
    2023_BMP_10_1_Bioretention_Systems.md
  raw/
    2023_BMP_10_1_Bioretention_Systems/
      manifest.json
      response.json
      pages/
```

## Which Version Should I Use?

Use the file that matches your task:

- Need the official document itself:
  Open the PDF at the family root.
- Need readable text for review, comparison, or report drafting:
  Open the Markdown file in `Markdown/`.
- Need to verify extraction quality or inspect the OCR evidence:
  Open the bundle in `raw/`.

## What the `citations` Folder Is For

`Sources/citations` is the canonical citation layer for this repo.

Important files:

- `source_document_registry.json`
  Master identity and path registry for source documents.
- `bmp_crosswalk.json` and `bmp_crosswalk.md`
  BMP-to-BMP mapping and comparison artifacts.
- `njac_section_index.json`
  Structured index for NJAC sections.
- `raw_index.json`
  Index of the raw OCR evidence bundles.
- `report_claims.json` and `report_claims.md`
  Traceability artifacts for authored report claims.
- `frontmatter_template.md`
  Frontmatter contract for `Sources/*/Markdown/*.md`.
- `README.md`
  Technical notes about raw evidence and citation maintenance.

If you are maintaining citations, use `Sources/citations` only. It is the canonical location.

## Common Ways to Use This Folder

### 1. Check a report claim

1. Find the topic in `docs/reports`.
2. Open the matching source family under `docs/Sources`.
3. Read the extracted Markdown in `Markdown/`.
4. If the text looks questionable, inspect the corresponding `raw/` evidence bundle or the PDF.

### 2. Compare 2023 vs. 2026

1. Open the 2023 chapter in `BMP_2023/Markdown/`.
2. Open the matching 2026 chapter in `BMP_2026/Markdown/`.
3. Use `citations/bmp_crosswalk.*` if you need structured mapping support.

### 3. Verify what source file a document came from

1. Start with `citations/source_document_registry.json`.
2. Use the registry path to find the PDF, Markdown twin, or raw evidence bundle.

### 4. Validate OCR or extraction quality

1. Open the Markdown file.
2. Compare it against the PDF.
3. If needed, inspect `raw/<doc_id>/manifest.json`, `response.json`, and any page images.

## Practical Rules

- Treat `docs/Sources` as the repo's source authority.
- Prefer `Markdown/` for normal reading and comparison work.
- Go back to the PDF or `raw/` bundle when something looks incomplete, distorted, or overstated.
- Treat `Sources/citations` as the only maintained citation authority.
- Do not recreate old `*_OCR` or `*_EXTRACTED` folder conventions.

## Where To Go Next

- Want the technical contract:
  Open [sources-readme.md](./sources-readme.md)
- Want citation maintenance details:
  Open [citations/README.md](./citations/README.md)
- Want the source registry:
  Open [citations/source_document_registry.json](./citations/source_document_registry.json)

As of `2026-04-09`, this page is the plain-language entry point for working inside `docs/Sources`.
