headless-gtm-shared - the chain's record contract and helpers

This folder is a library, not a skill. Nothing invokes it directly. It ships as a skill folder for one reason: the SKILL.md marker is what makes skill installers copy a directory, and every chain skill depends on this one.

What is in here

File	What it is	Who uses it
CONVENTIONS.md	The chain contract: JSONL records, additive per-stage fields, the runs/<run-id>/ layout, deviation logging	Every chain skill references it; read it before changing any output format
common.py	.env loading, the >$10 cost gate, output-dir resolution, run slugs, run metadata	Imported by the chain scripts
schema.py	ProspectRecord construction and the CSV/JSON writers	Imported by the discovery scripts
requirements.txt	The full dependency list for the chain, mirrored at the repo root	pip install

If you are reading this because an import failed

A script exited with cannot find headless-gtm-shared/common.py. The skill was copied out without this folder. Copy skills/headless-gtm-shared/ next to the skill that failed, so the layout is:

<skills-dir>/
├── headless-gtm-shared/          <- this folder
├── 02-apify-maps-discover/
└── ...

The npx skills add installer picks this folder up on its own. Only a manual single-folder copy can miss it.

Two rules worth knowing before you edit anything here

• common.load_env() never overwrites an exported variable. A real shell export or a secrets manager always beats a .env on disk. The loader only fills in what is missing.
• common.resolve_out_dir() writes under the current working directory, not under the skill. An installed skill is a read-only package; client output belongs in the project you are working in.