Skip to content

Using the Sources catalog

This folder is a reference knowledge base for New Jersey stormwater and soil erosion work. Use it to locate evidence, answer questions with citations, and report extraction or source problems. Inherit the repository's instructions when working inside the full Green Guides checkout.

Sources/ is the maintained baseline in the structured V2 format. The earlier catalog is kept separately as Sources (Legacy)/. A standalone Sources.zip extraction includes all local reference copies required for this catalog.

Find the evidence

  1. Start with README.md and choose NJAC, BMP, SESC, Tables, or Spreadsheets. Search the source folders rather than treating this guide or bug reports as technical evidence. For example:
rg -n -i "green roof" BMP NJAC -g "*.md"
  1. Resolve the matching document in catalog.json. Parse/filter the catalog instead of loading every record into the conversation. Select by document_id, title, source_kind, and printed revision. A collection folder's year is not necessarily the document's revision. Two editions can share a version_year; retain the full document identity.
  2. Read the source folder's README.md for context, tables.md for extracted tables, and the cited original page before relying on a consequential number, comparison, exemption, formula, or footnote. SOURCE.pdf preserves the original layout and figures. A missing text-search result does not establish that the original source has no relevant provision.
  3. Answer from the selected evidence. Give the edition and a compact locator, such as NJAC 7.8-5.2(f), Table 5-1, BMP 2026, Ch 9.4, p. 7, or SESC 2017, PDF p. 30, with a link to the local source or reading view. Distinguish PDF page numbers from printed page numbers when they differ. For a workbook, cite its title, worksheet name, and exact cell or range.
  4. If a discrepancy affects the answer, state what the source supports and what remains uncertain. Record the reproducible problem in bugs.md using its template.

Catalog and record locations

  • documents identifies the sources and their revisions, hashes, reading views, and record files. records maps record_id to document_id, chunk_id, relative path, and one-based JSONL line. tables is a table-record index.
  • readme, source_file, records_path, tables_path, table_records_path, and snapshot_path are relative to this knowledge-base root.
  • source_pdf, source_markdown, source_workbook, and reference_pdf identify original catalog inputs; resolve them against the catalog's source_root. Prefer source_file when opening the local reference copy. The original-input paths are provenance pointers and require the separate legacy collection; ordinary use of this package does not require it.
  • assets indexes original Mistral image crops. Their path is relative to this knowledge-base root; local_path is relative to the owning source folder. Each source's figures.md displays its crops and images.json preserves the source PDF/hash, one-based pdf_page, OCR image ID, pixel bounding box, dimensions, original extraction pointers, and record associations.
  • asset_ids on record/table index entries associate crops by PDF page. direct_asset_ids identifies images embedded at an exact matching OCR placeholder. A shared page does not prove a crop depicts a given table or supports every statement on that page. Read the image and original context.
  • table_number is a stable local ID and HTML-anchor number; table_order is its position in the current reading view. Use source_table_id for a printed table number when available. New tables receive new IDs without reassigning existing records, so ID order and reading order can differ.
  • image_count counts preserved extraction assets; display_image_count counts distinct crops shown to readers. Identical aliases on the same document page and bounds share a display_asset_id. All original paths, hashes and asset IDs remain in the index; different editions and crop locations are kept separate.
  • records.jsonl and tables.jsonl contain one JSON object per line with metadata, programmatic_checks, and content_markdown. IDs and provenance live in the catalog, outside those objects. Preserve document IDs and hashes when exporting records. For retrieval, group repeated content by chunk_id.

Interpret sources correctly

  • Establish which rule edition governs the project before giving a compliance conclusion. Preserve the distinction between NJAC, BMP guidance, SESC standards, model ordinances, worksheets, and comparison/redline documents. A document's presence in the library does not establish its applicability.
  • source_kind: table_reference means tables and page context are indexed; the local PDF contains the full reference. Redline extractions require the PDF to distinguish additions and deletions from final wording.
  • Preserve units, comparison operators, alternatives, configurations, notes, and exceptions. A single required_value is an extracted quantity, not an executable compliance test. It can represent a credited rate or one bound of a range. An empty check object does not mean the source contains no quantitative rules.
  • Keep zero, missing values, prohibited credits, and errors distinct. Some table headers, merged cells, superscripts, diagrams, and equations require visual inspection of SOURCE.pdf; extracted table text alone is insufficient proof.

Workbooks

Open the folder's original SOURCE.xls, SOURCE.xlsx, or SOURCE.xlsm for the workbook itself. Its SOURCE.pdf is a related BMP chapter, not a PDF rendering of the workbook. workbook.json and worksheet Markdown preserve source cells, formulas, cached results, and hidden sheets for lookup. Cached results are not fresh calculations. Preserve formula errors as errors; the legacy recharge workbook's known broken references are documented in bugs.md.

Keep source workbooks and PDFs unchanged. Formula execution, macro execution, external-link updates, and calculator repairs are separate tasks requiring the user's request; ordinary catalog lookup does not require them.

Report and maintain

Append distinct issues to bugs.md, retaining previous reports and their evidence. Distinguish a V2 extraction defect, an original-source defect, and an unconfirmed applicability or interpretation question. Share the completed report with the user for return to the maintainers. Send or upload it elsewhere only when the user explicitly requests that action.

For requested repairs in the full repository, read .agents/scripts/sources-v2/README.md from the repository root. Generated readable chapters, JSONL, and the catalog are rebuilt from their owning inputs; repair the owning source or extraction step and verify the result. Preserve the original reference binaries and existing feedback. These root guides and bugs.md are manually maintained and must survive rebuilds.