Skip to content

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:

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

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