How to generate and tune a ContosoForge dataset — running main.py, choosing output format, sizing rows/customers/stores, picking the business shape (trend preset), setting the date range, and selecting the product catalog. Use this whenever the user wants to produce data, change the scale or row counts, make the charts look a certain way (spikier/smoother/growing/declining/seasonal), adjust the date range, choose contoso vs synthetic products, or understand the config.yaml-vs-models.yaml split. Also use for "why do my charts look flat", "how many customers should I use", "--only sales", "--regen-dimensions", or any question about tuning generation output. Reach for it even when the user doesn't say "generate" explicitly but is clearly trying to shape the output data.
How ContosoForge generates multi-dialect SQL (SQL Server + PostgreSQL) and runs live database imports. Load this when editing anything under src/tools/sql/ — the pluggable dialect classes, CREATE TABLE / BULK INSERT / COPY / constraint / view generators, or the sql_server_import.py / postgres_import.py runners. Also use it when adding a new SQL dialect, changing generated DDL, debugging escaping of paths or names in generated scripts, or working on the CSV-to-database load path. Reach for it on any "the generated SQL is broken / wrong quoting / import fails" question.
How ContosoForge's configuration is typed and validated — the Pydantic spine in src/engine/config/config_schema.py, the normalizer registry in config.py, and the coercion helpers in src/utils/config_helpers.py. Load this when adding or changing a config field, editing config validation/normalization, writing code that reads cfg or models_cfg, or debugging a config validation error. Its single most important point: BOTH cfg and models_cfg are Pydantic models, not dicts — access fields by attribute. Use it whenever you see AttributeError/ValidationError on config, need to add a new config.yaml or models.yaml key, or aren't sure whether to use dict or attribute access on a config object.
The determinism, parallelism, and numeric-safety contract for the sales fact generator (src/facts/sales/). Load this BEFORE editing anything under src/facts/sales/ — chunk building, the worker pool, customer sampling, pricing, promotions, allocation, delivery, or the State object. It explains why the sales fact must be byte-identical regardless of --workers and --chunk-size, the rules for worker-lifetime caches and hash-seeded draws, the ID-arithmetic and numpy pitfalls that silently corrupt output, and the golden-snapshot test workflow. Use it whenever you touch sales generation, see a determinism/snapshot test fail, add a correlated-fact feature, or need to regenerate the sales fingerprint baseline.
Conventions and safety rules for the ContosoForge web layer — the FastAPI backend (web/api.py, web/routes/, web/shared_state.py) and its React SPA (web/frontend/). Load this when editing anything under web/ — adding or changing an API endpoint, touching shared mutable state, or working on CORS/security/payload handling. It covers the thread-safety locking discipline, the dual (/api + /v1/api) route versioning, the CORS allowlist and security headers, and the request-size limits. Use it for any "add an endpoint", "the web UI", "FastAPI route", or "why is the API rejecting my request" work.