@yottagraph-app/data-model-skill 0.0.35 → 0.0.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottagraph-app/data-model-skill",
-  "version": "0.0.35",
+  "version": "0.0.37",
   "description": "Data model skill documentation for AI agents - entity types, properties, and schemas from Lovelace fetch sources",
   "repository": {
     "type": "git",

package/skill/blscew/DATA_DICTIONARY.md

@@ -0,0 +1,389 @@
+# Data Dictionary: BLS CEW (QCEW)
+
+## Purpose
+
+This dictionary documents the entity types, properties, and attributes
+that the BLS Quarterly Census of Employment and Wages (QCEW) source
+contributes to the Lovelace knowledge graph. It is the contract between
+the source and downstream consumers (ingest, query server, UI).
+
+QCEW is a quarterly count of employment and wages reported by employers,
+covering more than 95 % of US jobs. It is published by the U.S. Bureau
+of Labor Statistics for every state, MSA, and county, broken out by
+ownership (federal/state/local/private) and by industry (NAICS), at the
+sector / 3-digit / 4-digit / 5-digit / 6-digit detail levels. The
+Lovelace QCEW source ingests the published quarterly data slices —
+specifically the by-area CSV slices for the United States as a whole
+plus all 50 states and DC — and emits one record per area × ownership ×
+industry × quarter combination.
+
+**Pipeline:** Download → Extract → Atomize.
+- Download fetches the per-area CSV slice for each (area, year, quarter)
+  from `https://data.bls.gov/cew/data/api/{year}/{quarter}/area/{area_fips}.csv`.
+- Extract is a pass-through (the raw CSV is the structured input).
+- Atomize parses each CSV row into KG records.
+
+**Cadence:** BLS publishes each quarter's QCEW release roughly 5–7
+months after the close of the quarter (Q1 in late Aug/Sep, Q2 in late
+Nov/Dec, Q3 in early Mar of the next year, Q4 in early Jun). The
+streamer polls weekly; new quarters are detected and atomized when they
+appear.
+
+**Disclosure suppression.** Rows with `disclosure_code == "N"` are
+withheld by BLS to protect employer confidentiality (typically when an
+industry has very few establishments in an area). All numeric values on
+those rows are zero. The atomizer drops "N"-disclosed rows entirely so
+the KG never contains zero-valued QCEW observations that would be
+mistaken for real data.
+
+**Series identity.** A QCEW "series" is uniquely identified by the
+4-tuple (area_fips, own_code, industry_code, agglvl_code). The atomizer
+constructs a synthetic series id of the form
+`{area_fips}.{own_code}.{industry_code}.{agglvl_code}` and emits this
+as the `cew_series_id` strong id on a `cew_series` entity. `size_code`
+is always `0` for the quarterly area slices ingested today (size-class
+slices are an annual-only artifact and are out of scope for v1).
+
+**Source name:** `blscew-source`
+
+---
+
+## Entity Types
+
+### `cew_series`
+
+A single QCEW time series — the unique combination of geographic area,
+ownership, industry, and aggregation level — that carries quarterly
+employment, wages, and establishment metrics over time.
+
+- Primary key: `cew_series_id` (synthetic id, see above) used as the
+  strong id for resolution.
+- Entity resolver: named entity, NOT_MERGEABLE. The strong id is
+  `cew_series_id`. The disambiguation snippet includes area title,
+  ownership title, industry title, and aggregation level title.
+- Source: `blscew-source`
+- Examples produced: `US000.0.10.10` (US national, total ownership, all
+  industries), `06000.5.31-33.55` (California, private ownership,
+  Manufacturing supersector), `06037.0.5111.74` (Los Angeles County,
+  total ownership, NAICS 5111 Newspaper / Periodical Publishers).
+
+### `location`
+
+A US geographic area (national, state, MSA, or county) for which BLS
+publishes QCEW data, identified by its FIPS-based `area_fips` code.
+
+- Primary key: `area_fips` strong id.
+- Entity resolver: named entity, NOT_MERGEABLE. Strong id is
+  `area_fips`. Snippet includes the area title and the area type
+  (national / statewide / MSA / county).
+- Source: `blscew-source`
+- Examples produced: `US000` (U.S. TOTAL), `06000` (California -- Statewide),
+  `06037` (Los Angeles County, California), `C1018` (Albany-Schenectady-Troy,
+  NY MSA).
+
+### `industry`
+
+An economic activity category from the North American Industry
+Classification System (NAICS), or a BLS-defined supersector that rolls
+up multiple NAICS sectors.
+
+- Primary key: `naics_code` strong id (the BLS QCEW `industry_code`,
+  which can be a NAICS sector / 3-digit / 4-digit / 5-digit / 6-digit
+  code, a 2-digit BLS supersector aggregate (e.g. `31-33` for
+  Manufacturing), or the special aggregate `10` meaning "Total, all
+  industries").
+- Entity resolver: named entity, NOT_MERGEABLE. Strong id is
+  `naics_code`. Snippet includes the industry title.
+- Source: `blscew-source`
+- Examples produced: `10` (Total, all industries), `31-33`
+  (Manufacturing), `5111` (Newspaper, Periodical, Book, and Directory
+  Publishers), `541` (Professional, Scientific, and Technical Services).
+
+---
+
+## Properties
+
+### Identity & Metadata Properties (cew_series)
+
+These atoms appear once per series, timestamped at the first quarter
+the series is observed in the current run.
+
+* `cew_series_id`
+  * Definition: synthetic identifier for a QCEW series, built by
+    joining the area, ownership, industry, and aggregation-level codes
+    with dots.
+  * Examples: `"US000.0.10.10"`, `"06000.5.31-33.55"`,
+    `"06037.0.5111.74"`
+  * Derivation: built by the atomizer from the QCEW `area_fips`,
+    `own_code`, `industry_code`, and `agglvl_code` fields of each CSV
+    row.
+
+* `name`
+  * Definition: human-readable label for the series, combining area,
+    ownership, and industry titles.
+  * Examples: `"U.S. TOTAL · Total Covered · Total, all industries"`,
+    `"California · Private · Manufacturing"`
+  * Derivation: built from the `area_title`, `own_title`, and
+    `industry_title` fields on the CSV row.
+
+* `area_fips`
+  * Definition: BLS-assigned 5-character area identifier (FIPS-based).
+    Acts as strong id on the `location` entity that the series points
+    to.
+  * Examples: `"US000"`, `"06000"`, `"06037"`, `"C1018"`
+  * Derivation: `area_fips` field of the CSV row.
+
+* `area_title`
+  * Definition: human-readable title for the geographic area.
+  * Examples: `"U.S. TOTAL"`, `"California -- Statewide"`,
+    `"Los Angeles County, California"`,
+    `"Albany-Schenectady-Troy, NY MSA"`
+  * Derivation: `area_title` field of the CSV row.
+
+* `ownership_code`
+  * Definition: BLS one-character code identifying the ownership
+    sector covered by the series.
+  * Examples: `"0"` (Total Covered), `"1"` (Federal Government),
+    `"2"` (State Government), `"3"` (Local Government),
+    `"5"` (Private)
+  * Derivation: `own_code` field of the CSV row.
+
+* `ownership_title`
+  * Definition: human-readable label for the ownership sector.
+  * Examples: `"Total Covered"`, `"Federal Government"`,
+    `"State Government"`, `"Local Government"`, `"Private"`
+  * Derivation: `own_title` field of the CSV row.
+
+* `naics_code`
+  * Definition: industry code used by BLS — NAICS at varying levels of
+    aggregation, plus BLS supersector aggregates and the special
+    "Total, all industries" code `10`. Acts as strong id on the
+    `industry` entity that the series points to.
+  * Examples: `"10"`, `"31-33"`, `"5111"`, `"541211"`
+  * Derivation: `industry_code` field of the CSV row.
+
+* `naics_description`
+  * Definition: human-readable name of the industry / supersector.
+  * Examples: `"Total, all industries"`, `"Manufacturing"`,
+    `"Newspaper, periodical, book and directory publishers"`
+  * Derivation: `industry_title` field of the CSV row.
+
+* `aggregation_level_code`
+  * Definition: BLS two-character code describing the geographic and
+    industry aggregation level the series represents (e.g. national
+    total, statewide ownership × supersector, county × 6-digit NAICS).
+  * Examples: `"10"` (national, by ownership × total), `"55"`
+    (statewide, by ownership × supersector),
+    `"74"` (county, by ownership × 5-digit NAICS),
+    `"78"` (county, by ownership × 6-digit NAICS)
+  * Derivation: `agglvl_code` field of the CSV row.
+
+* `aggregation_level_title`
+  * Definition: human-readable description of the aggregation level.
+  * Examples: `"National, by ownership sector"`,
+    `"Statewide, by ownership sector and supersector"`,
+    `"County, by ownership sector and 6-digit NAICS"`
+  * Derivation: `agglvl_title` field of the CSV row.
+
+* `area_type`
+  * Definition: classification of the area as one of `national`,
+    `statewide`, `msa`, or `county` derived from the leading characters
+    of `area_fips` and the trailing zeros pattern.
+  * Examples: `"national"`, `"statewide"`, `"county"`, `"msa"`
+  * Derivation: heuristic on `area_fips`: `US000` → national; FIPS
+    starting with `C` → MSA; 5-digit ending in `000` → statewide; any
+    other 5-digit code → county.
+
+* `naics_level`
+  * Definition: granularity of the NAICS code on this row, where
+    higher values are more specific. Stored as a float to keep with
+    the schema's float-for-numeric convention.
+  * Examples: `2.0` (sector or supersector), `3.0` (subsector),
+    `4.0` (industry group), `5.0` (NAICS industry), `6.0` (national
+    industry).
+  * Derivation: length of the `industry_code` string, with the special
+    case `10` (Total) and any 2-character supersector code mapped to
+    `2.0`.
+
+* `publisher`
+  * Definition: organization that publishes the data (always BLS).
+  * Examples: `"U.S. Bureau of Labor Statistics"`
+  * Derivation: hard-coded constant; QCEW is exclusively a BLS product.
+
+### Quarterly Observation Properties (cew_series)
+
+These atoms appear on the per-quarter observation records, timestamped
+at the last day of the quarter (e.g. 2024-03-31 for Q1 2024).
+
+* `establishment_count`
+  * Definition: count of establishments (physical locations of
+    employers) covered by the series in the quarter.
+  * Examples: `11907855` (US total Q1 2024), `61375` (US Federal
+    Government total Q1 2024)
+  * Derivation: `qtrly_estabs` field of the CSV row.
+
+* `monthly_employment_m1`, `monthly_employment_m2`, `monthly_employment_m3`
+  * Definition: number of employees on payrolls covered in the first /
+    second / third month of the quarter (BLS uses the pay period
+    including the 12th of the month).
+  * Examples (US Q1 2024 total): `152393725`, `153129544`, `153848430`
+  * Derivation: `month1_emplvl`, `month2_emplvl`, `month3_emplvl`
+    fields of the CSV row.
+
+* `employment_level`
+  * Definition: representative quarterly employment level for the
+    series, taken as the third-month employment (final month of the
+    quarter), aligned to the way QCEW publications report "QCEW
+    employment".
+  * Examples: `153848430` (US Q1 2024 total)
+  * Derivation: `month3_emplvl` field of the CSV row.
+
+* `total_quarterly_wages`
+  * Definition: total wages paid (in current US dollars) to all covered
+    workers during the quarter.
+  * Examples: `3037790324790` (US Q1 2024 total = $3.04 trillion)
+  * Derivation: `total_qtrly_wages` field of the CSV row.
+
+* `taxable_quarterly_wages`
+  * Definition: portion of total quarterly wages subject to UI tax
+    contributions (in current US dollars). Always 0 for federal
+    government employment, which is not subject to UI tax.
+  * Examples: `1151875077520` (US Q1 2024 total)
+  * Derivation: `taxable_qtrly_wages` field of the CSV row.
+
+* `quarterly_contributions`
+  * Definition: total UI tax contributions (in current US dollars)
+    associated with this employment in the quarter.
+  * Examples: `19555346530` (US Q1 2024 total)
+  * Derivation: `qtrly_contributions` field of the CSV row.
+
+* `avg_weekly_wage`
+  * Definition: average weekly wage (in current US dollars) per
+    employee covered in the quarter, computed by BLS as
+    `total_qtrly_wages / (avg_emplvl × 13)`.
+  * Examples: `1526` (US Q1 2024 total = $1,526/week)
+  * Derivation: `avg_wkly_wage` field of the CSV row.
+
+### Year-over-Year Change Properties (cew_series)
+
+BLS pre-computes over-the-year (OTY) absolute and percent changes for
+each quarterly metric, comparing the current quarter to the same quarter
+of the prior year. The atomizer emits the percent-change variants as
+their own atoms so downstream consumers can directly query
+"Employment growth YoY" without recomputing it from observation history.
+
+* `employment_yoy_pct_chg`
+  * Definition: year-over-year percent change in the canonical
+    `employment_level` (= third-month / end-of-quarter snapshot).
+  * Examples: `1.5` (US total Q1 2024 vs Q1 2023 = +1.5 %)
+  * Derivation: `oty_month3_emplvl_pct_chg` field of the CSV row. We
+    intentionally do *not* also emit `monthly_employment_m3_yoy_pct_chg`
+    -- it would duplicate this number under a redundant property name.
+
+* `monthly_employment_m1_yoy_pct_chg`, `monthly_employment_m2_yoy_pct_chg`
+  * Definition: year-over-year percent change in mid-quarter monthly
+    employment (the M1 and M2 snapshots that have no canonical alias;
+    the M3 snapshot is exposed as `employment_yoy_pct_chg` above).
+  * Examples (US Q1 2024 total): `1.4`, `1.4`
+  * Derivation: `oty_month1_emplvl_pct_chg`, `oty_month2_emplvl_pct_chg`,
+    `oty_month3_emplvl_pct_chg` fields of the CSV row.
+
+* `establishments_yoy_pct_chg`
+  * Definition: year-over-year percent change in the count of
+    establishments.
+  * Examples: `1.2` (US Q1 2024 total = +1.2 %)
+  * Derivation: `oty_qtrly_estabs_pct_chg` field of the CSV row.
+
+* `total_quarterly_wages_yoy_pct_chg`
+  * Definition: year-over-year percent change in total quarterly
+    wages.
+  * Examples: `5.7` (US Q1 2024 total = +5.7 %)
+  * Derivation: `oty_total_qtrly_wages_pct_chg` field of the CSV row.
+
+* `avg_weekly_wage_yoy_pct_chg`
+  * Definition: year-over-year percent change in the average weekly
+    wage.
+  * Examples: `4.2` (US Q1 2024 total = +4.2 %)
+  * Derivation: `oty_avg_wkly_wage_pct_chg` field of the CSV row.
+
+* `taxable_quarterly_wages_yoy_pct_chg`
+  * Definition: year-over-year percent change in taxable quarterly
+    wages.
+  * Examples: `3.3`
+  * Derivation: `oty_taxable_qtrly_wages_pct_chg` field of the CSV row.
+
+* `quarterly_contributions_yoy_pct_chg`
+  * Definition: year-over-year percent change in UI contributions.
+  * Examples: `4.3`
+  * Derivation: `oty_qtrly_contributions_pct_chg` field of the CSV row.
+
+### Location Properties (location)
+
+* `area_fips`
+  * Definition: BLS-assigned area identifier (FIPS-based) used as the
+    location's strong id.
+  * Examples: `"US000"`, `"06000"`, `"06037"`, `"C1018"`
+  * Derivation: `area_fips` field of the CSV row.
+
+* `name`
+  * Definition: human-readable name of the geographic area.
+  * Examples: `"U.S. TOTAL"`, `"California -- Statewide"`,
+    `"Los Angeles County, California"`
+  * Derivation: `area_title` field of the CSV row.
+
+* `area_type`
+  * Definition: classification of the area as `national`, `statewide`,
+    `msa`, or `county`.
+  * Examples: `"national"`, `"statewide"`, `"county"`, `"msa"`
+  * Derivation: heuristic on `area_fips`; see the `cew_series` entry of
+    the same name above.
+
+### Industry Properties (industry)
+
+* `naics_code`
+  * Definition: industry code used by BLS (NAICS at sector / 3-digit /
+    4-digit / 5-digit / 6-digit detail, plus BLS supersector aggregates
+    and `10` = Total, all industries). Strong id for `industry`.
+  * Examples: `"10"`, `"31-33"`, `"5111"`, `"541211"`
+  * Derivation: `industry_code` field of the CSV row.
+
+* `naics_description`
+  * Definition: human-readable industry name.
+  * Examples: `"Total, all industries"`, `"Manufacturing"`,
+    `"Newspaper, periodical, book and directory publishers"`
+  * Derivation: `industry_title` field of the CSV row.
+
+* `naics_level`
+  * Definition: granularity of the NAICS code (see the `cew_series`
+    entry of the same name above for derivation).
+  * Examples: `2.0`, `3.0`, `4.0`, `5.0`, `6.0`
+
+---
+
+## Entity Relationships Summary
+
+The QCEW source emits two relationship types — both pointing from the
+real-world contextual entity (a US area or an industry) to the
+`cew_series` it appears in. This mirrors the FRED source's
+`appears_in_fred_series` pattern.
+
+```
+location  ──[appears_in_cew_series]──→ cew_series
+industry  ──[appears_in_cew_series]──→ cew_series
+```
+
+* `appears_in_cew_series`
+  * Definition: the subject (a US geographic area or an industry)
+    appears as the area / industry dimension of a QCEW time series.
+  * Domain flavors: `location`, `industry`
+  * Target flavor: `cew_series`
+  * Derivation: emitted once per series per quarter on the location and
+    industry context records.
+
+---
+
+## Attributes
+
+None. All quarterly metrics are timestamped scalar atoms; there are no
+per-atom attributes (unit / frequency / etc.) on this source — those are
+carried as atoms on the `cew_series` metadata record.

package/skill/blscew/schema.yaml

@@ -0,0 +1,345 @@
+# Dataset schema for BLS QCEW (Quarterly Census of Employment and Wages).
+#
+# Architecture mirrors FRED:
+#   For each unique QCEW series — the (area_fips, own_code, industry_code,
+#   agglvl_code) tuple — the atomizer emits:
+#     1. A metadata record: subject is the cew_series entity, atoms are
+#        identifying metadata (cew_series_id, area_fips, area_title,
+#        ownership_code/title, naics_code/description, aggregation level,
+#        publisher, etc.). Timestamped at the quarter end date.
+#     2. One quarterly observation record per (series, quarter): subject is
+#        the cew_series, atoms are all quarterly metrics — establishment
+#        count, employment levels, wages, year-over-year percent changes —
+#        all timestamped at the quarter end date.
+#     3. A location context record: subject is the geographic area
+#        (location flavor), single appears_in_cew_series atom pointing at
+#        the cew_series.
+#     4. An industry context record: subject is the NAICS industry
+#        (industry flavor), single appears_in_cew_series atom pointing at
+#        the cew_series.
+#
+# All elements are passive — created by the atomizer from QCEW CSV data,
+# not by LLM extraction.
+#
+# Source identifier used on all records: "blscew-source"
+name: "blscew"
+description: "Quarterly Census of Employment and Wages from the U.S. Bureau of Labor Statistics — quarterly establishment counts, employment levels, total and taxable wages, average weekly wages, and BLS-computed year-over-year changes by US area, ownership sector, and NAICS industry"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - name: "cew_series"
+    description: "A QCEW (Quarterly Census of Employment and Wages) time series identified by the unique combination of area, ownership, industry, and aggregation level. The entity carries metadata atoms and per-quarter observations of employment, wages, and establishment counts."
+    display_name: "QCEW Series"
+    mergeability: not_mergeable
+    strong_id_properties: ["cew_series_id"]
+    passive: true
+
+  - name: "location"
+    description: "A specific named geographic location such as a city, country, region, or landmark"
+    display_name: "Location"
+    mergeability: not_mergeable
+    strong_id_properties: ["area_fips"]
+    passive: true
+
+  - name: "industry"
+    description: "An industry classification of economic activity (e.g. NAICS or SIC) identifying the line of business associated with an organization or award"
+    display_name: "Industry"
+    mergeability: not_mergeable
+    strong_id_properties: ["naics_code"]
+    passive: true
+
+properties:
+  # --- Strong-id properties ---
+
+  - name: "cew_series_id"
+    type: string
+    description: "Synthetic identifier for a QCEW series formed by joining area_fips, own_code, industry_code, and agglvl_code with dots. Strong id for cew_series entities."
+    display_name: "QCEW Series ID"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["US000.0.10.10", "06000.5.31-33.55", "06037.0.5111.74"]
+    passive: true
+
+  - name: "area_fips"
+    type: string
+    description: "BLS-assigned 5-character QCEW area identifier (FIPS-based). For US states the value is the 2-digit FIPS state code followed by '000' (e.g. '06000' = California). For counties it is the 5-digit county FIPS (e.g. '06037' = Los Angeles County). For MSAs the BLS prefixes a 'C' (e.g. 'C1018' = Albany–Schenectady–Troy MSA). Strong id for the location entity that a cew_series is attached to."
+    display_name: "QCEW Area FIPS"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "location"]
+    examples: ["US000", "06000", "06037", "C1018"]
+    passive: true
+
+  - name: "naics_code"
+    type: string
+    description: "North American Industry Classification System code (typically 6 digits) identifying the industry of work performed under a contract (e.g., \"524114\" for Direct Health and Medical Insurance Carriers)"
+    display_name: "NAICS code"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "industry"]
+    examples: ["10", "31-33", "5111", "541211"]
+    passive: true
+
+  # --- Identity / metadata properties on cew_series ---
+
+  - name: "name"
+    type: string
+    description: "Display name of the entity"
+    display_name: "Name"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "location"]
+    examples: ["California -- Statewide", "U.S. TOTAL · Total Covered · Total, all industries"]
+    passive: true
+
+  - name: "area_title"
+    type: string
+    description: "Human-readable title for a QCEW geographic area (national, state, MSA, or county) as published by BLS."
+    display_name: "QCEW Area Title"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["U.S. TOTAL", "California -- Statewide", "Los Angeles County, California", "Albany-Schenectady-Troy, NY MSA"]
+    passive: true
+
+  - name: "ownership_code"
+    type: string
+    description: "BLS one-character QCEW ownership-sector code: 0 = Total Covered, 1 = Federal Government, 2 = State Government, 3 = Local Government, 5 = Private."
+    display_name: "QCEW Ownership Code"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["0", "1", "2", "3", "5"]
+    passive: true
+
+  - name: "ownership_title"
+    type: string
+    description: "Human-readable QCEW ownership-sector title (Total Covered, Federal Government, State Government, Local Government, Private)."
+    display_name: "QCEW Ownership Title"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["Total Covered", "Federal Government", "State Government", "Local Government", "Private"]
+    passive: true
+
+  - name: "naics_description"
+    type: string
+    description: "Human-readable name of the NAICS industry (e.g., \"DIRECT HEALTH AND MEDICAL INSURANCE CARRIERS\")"
+    display_name: "NAICS description"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "industry"]
+    examples: ["Total, all industries", "Manufacturing", "Newspaper, periodical, book and directory publishers"]
+    passive: true
+
+  - name: "aggregation_level_code"
+    type: string
+    description: "BLS QCEW two-character aggregation-level code describing the geographic and industry granularity of a series — for example national vs statewide vs county, and total vs supersector vs detailed NAICS."
+    display_name: "QCEW Aggregation Level Code"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["10", "55", "74", "78"]
+    passive: true
+
+  - name: "aggregation_level_title"
+    type: string
+    description: "Human-readable description of a QCEW aggregation level (e.g. \"National, by ownership sector\", \"County, by ownership sector and 6-digit NAICS\")."
+    display_name: "QCEW Aggregation Level Title"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["National, by ownership sector", "Statewide, by ownership sector and supersector", "County, by ownership sector and 6-digit NAICS"]
+    passive: true
+
+  - name: "area_type"
+    type: string
+    description: "Classification of a QCEW area as one of national, statewide, msa, or county, derived from the shape of the area_fips code."
+    display_name: "QCEW Area Type"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "location"]
+    examples: ["national", "statewide", "msa", "county"]
+    passive: true
+
+  - name: "naics_level"
+    type: float
+    description: "Granularity of the NAICS code on a QCEW series, expressed as the number of digits. 2.0 = sector or BLS supersector aggregate, 3.0 = subsector, 4.0 = industry group, 5.0 = NAICS industry, 6.0 = national industry."
+    display_name: "QCEW NAICS Level"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series", "industry"]
+    examples: [2.0, 3.0, 4.0, 5.0, 6.0]
+    passive: true
+
+  - name: "publisher"
+    type: string
+    description: "Name of the organization that publishes or maintains the data series, inferred from the release URL domain"
+    display_name: "Publisher"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: ["U.S. Bureau of Labor Statistics"]
+    passive: true
+
+  # --- Quarterly observation properties on cew_series ---
+
+  - name: "establishment_count"
+    type: float
+    description: "Count of QCEW-covered establishments (physical locations of employers) reported by BLS for the series during the quarter."
+    display_name: "QCEW Establishment Count"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [11907855.0, 61375.0]
+    passive: true
+
+  - name: "monthly_employment_m1"
+    type: float
+    description: "Number of QCEW-covered employees on payrolls in the first month of the quarter (BLS uses the pay period including the 12th of the month)."
+    display_name: "QCEW Employment (Month 1)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [152393725.0]
+    passive: true
+
+  - name: "monthly_employment_m2"
+    type: float
+    description: "Number of QCEW-covered employees on payrolls in the second month of the quarter (pay period including the 12th)."
+    display_name: "QCEW Employment (Month 2)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [153129544.0]
+    passive: true
+
+  - name: "monthly_employment_m3"
+    type: float
+    description: "Number of QCEW-covered employees on payrolls in the third month of the quarter (pay period including the 12th)."
+    display_name: "QCEW Employment (Month 3)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [153848430.0]
+    passive: true
+
+  - name: "employment_level"
+    type: float
+    description: "Representative quarterly employment level for the series — taken as the third-month employment, matching the convention BLS uses when publishing single-number QCEW employment figures."
+    display_name: "QCEW Quarterly Employment Level"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [153848430.0]
+    passive: true
+
+  - name: "total_quarterly_wages"
+    type: float
+    description: "Total wages paid (in current US dollars) to all QCEW-covered workers for the series during the quarter."
+    display_name: "QCEW Total Quarterly Wages (USD)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [3037790324790.0]
+    passive: true
+
+  - name: "taxable_quarterly_wages"
+    type: float
+    description: "Portion of total quarterly wages (in current US dollars) subject to UI tax contributions. Always 0 for federal-government employment, which is not subject to UI tax."
+    display_name: "QCEW Taxable Quarterly Wages (USD)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1151875077520.0]
+    passive: true
+
+  - name: "quarterly_contributions"
+    type: float
+    description: "Total UI tax contributions (in current US dollars) associated with the series' employment during the quarter."
+    display_name: "QCEW Quarterly UI Contributions (USD)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [19555346530.0]
+    passive: true
+
+  - name: "avg_weekly_wage"
+    type: float
+    description: "Average weekly wage (in current US dollars) per QCEW-covered employee for the series during the quarter, computed by BLS as total_qtrly_wages / (avg_emplvl × 13)."
+    display_name: "QCEW Average Weekly Wage (USD)"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1526.0]
+    passive: true
+
+  # --- BLS-computed year-over-year percent change properties on cew_series ---
+
+  - name: "employment_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in third-month employment for the series, computed by BLS by comparing the current quarter against the same quarter of the prior year."
+    display_name: "QCEW Employment YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1.5, -0.4]
+    passive: true
+
+  - name: "monthly_employment_m1_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in first-month employment for the series."
+    display_name: "QCEW Employment (Month 1) YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1.4]
+    passive: true
+
+  - name: "monthly_employment_m2_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in second-month employment for the series."
+    display_name: "QCEW Employment (Month 2) YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1.4]
+    passive: true
+
+  - name: "establishments_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in establishment count for the series."
+    display_name: "QCEW Establishments YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [1.2]
+    passive: true
+
+  - name: "total_quarterly_wages_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in total quarterly wages for the series."
+    display_name: "QCEW Total Wages YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [5.7]
+    passive: true
+
+  - name: "avg_weekly_wage_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in average weekly wage for the series."
+    display_name: "QCEW Avg Weekly Wage YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [4.2]
+    passive: true
+
+  - name: "taxable_quarterly_wages_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in taxable quarterly wages for the series."
+    display_name: "QCEW Taxable Wages YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [3.3]
+    passive: true
+
+  - name: "quarterly_contributions_yoy_pct_chg"
+    type: float
+    description: "Year-over-year percent change in quarterly UI contributions for the series."
+    display_name: "QCEW UI Contributions YoY %"
+    mergeability: not_mergeable
+    domain_flavors: ["cew_series"]
+    examples: [4.3]
+    passive: true
+
+relationships:
+  - name: "appears_in_cew_series"
+    description: "Links a real-world contextual entity (a US geographic area or a NAICS industry) to a QCEW time series whose area or industry dimension is that entity."
+    display_name: "Appears in QCEW Series"
+    mergeability: not_mergeable
+    domain_flavors: ["location", "industry"]
+    target_flavors: ["cew_series"]
+    passive: true
+
+attributes: []

package/skill/fips/DATA_DICTIONARY.md

@@ -0,0 +1,135 @@
+# Data Dictionary: FIPS Codes (FCC mirror)
+
+## Source Overview
+
+Federal Information Processing Standard (FIPS) codes for U.S. states and
+counties — short numeric identifiers issued by the federal government
+(Census Bureau / NIST historically) that uniquely tag every U.S. state,
+the District of Columbia, and every county-or-equivalent (boroughs,
+parishes, independent cities, census areas).
+
+- **Publisher (mirror):** U.S. Federal Communications Commission, Office
+  of Engineering and Technology
+- **URL:** https://transition.fcc.gov/oet/info/maps/census/fips/fips.txt
+- **Format:** Plain-text fixed-column ASCII, ~3,200 lines total
+- **Cadence:** Effectively static. The federal codes change only when
+  jurisdictions are created, dissolved, or renamed (rare — once every
+  several years).
+- **Source name:** `fips`
+
+The file contains two sections:
+
+1. A 51-row table of **state-level FIPS codes** (50 states + DC), one
+   line per state with a 2-digit code.
+2. A 3,140+ row table of **county-level FIPS codes**, one line per county
+   (or county-equivalent) with a 5-digit code. The leading 2 digits are
+   the parent state's FIPS code; the trailing 3 digits identify the
+   county within the state. The county-level table is grouped by state
+   and prefaced with a header row of the form `XX000  StateName`.
+
+**Limitations:**
+- The FCC mirror is a republication of the older Census-published list;
+  it does not include FIPS *places* (cities/towns), MSAs, or U.S.
+  territories (Puerto Rico, Guam, U.S. Virgin Islands, etc.).
+- A small number of county lines have parenthesized historical
+  annotations (`(created after 1990)`, `(1990 Census Area)`,
+  `(After 1990, part of Halifax County)`). These are stripped from the
+  emitted county name.
+- The `XX000` state header rows in the county section are duplicates of
+  the state-level table and are skipped during atomization (one record
+  per state, not two).
+
+---
+
+## Entity Types
+
+### `location`
+
+Used for both U.S. states (and DC) and U.S. counties (and county-
+equivalents like Alaska boroughs, Louisiana parishes, and Virginia
+independent cities). The level of geography is distinguished by which
+strong-ID property is set (`fips_state` for state-level, `fips_county`
+for county-level) and by the `administrative_level` property.
+
+- **Primary key (state-level):** the 2-digit FIPS state code, exposed as
+  the `fips_state` strong-ID property and as a property atom.
+- **Primary key (county-level):** the 5-digit FIPS county code, exposed
+  as the `fips_county` strong-ID property and as a property atom.
+- **Entity resolver:** named entity, **MERGEABLE**. State and county FIPS
+  codes are stable, official identifiers and merging across sources
+  (Census, FRED, sanctions data, etc.) is desired. Disambiguation
+  snippets include the formatted name (e.g. `"Autauga County, Alabama"`).
+- **Name format:**
+  - State-level: `Title-cased state name` (e.g. `"Alabama"`,
+    `"District of Columbia"`).
+  - County-level: `"{County} County, {State}"` for the common case;
+    parishes / boroughs / cities / census areas keep their original
+    suffix (e.g. `"East Baton Rouge Parish, Louisiana"`,
+    `"Aleutians East Borough, Alaska"`,
+    `"Baltimore city, Maryland"`).
+
+---
+
+## Properties
+
+The dataset uses the DataSchema `namespace: fips`. Atom property keys
+are `fips::<local_name>` for source-specific properties. Identity
+properties also used for resolver strong IDs are `fips_state` and
+`fips_county`.
+
+### Common Properties (states and counties)
+
+* `fips::administrative_level`
+  * Definition: Granularity of the geographic entity within the U.S.
+    federal hierarchy.
+  * Examples: `"state"`, `"county"`
+  * Derivation: Set to `"state"` for entries from the state-level table,
+    `"county"` for entries from the county-level table.
+
+* `fips::official_name`
+  * Definition: Verbatim place name as it appears in the FCC mirror,
+    upper-cased for states and mixed-case for counties.
+  * Examples: `"ALABAMA"`, `"Autauga County"`,
+    `"Aleutians East Borough"`, `"East Baton Rouge Parish"`,
+    `"Baltimore city"`
+  * Derivation: The "place name" column of the source file, with the
+    parenthesized historical annotation (when present) stripped.
+
+### State Properties
+
+* `fips_state`
+  * Definition: Two-digit Federal Information Processing Standard code
+    that uniquely identifies a U.S. state or the District of Columbia.
+  * Examples: `"01"` (Alabama), `"06"` (California), `"11"` (DC)
+  * Derivation: Verbatim from the state-level table's first column,
+    zero-padded to two digits.
+  * Note: Also used as the strong ID on the state's `location` entity.
+
+### County Properties
+
+* `fips_county`
+  * Definition: Five-digit Federal Information Processing Standard code
+    that uniquely identifies a U.S. county or county-equivalent. The
+    leading two digits are the parent state's `fips_state` code; the
+    trailing three digits identify the county within the state.
+  * Examples: `"01001"` (Autauga County, Alabama), `"06037"` (Los
+    Angeles County, California), `"22033"` (East Baton Rouge Parish,
+    Louisiana)
+  * Derivation: Verbatim from the county-level table's first column,
+    zero-padded to five digits.
+  * Note: Also used as the strong ID on the county's `location` entity.
+
+---
+
+## Entity Relationships Summary
+
+```
+location (county) ──[located_in]──→ location (state)
+```
+
+- `located_in`: Each county-level `location` is linked to its parent
+  state-level `location` via the leading two digits of the county FIPS
+  code. Both sides carry strong IDs (`fips_county` and `fips_state`),
+  which guarantees resolver merging into a single state node across all
+  county-→-state edges and across other datasets that emit the same
+  state codes.

package/skill/fips/schema.yaml

@@ -0,0 +1,77 @@
+# Dataset schema for the FIPS Codes (Federal Information Processing
+# Standard) source — the FCC mirror of the Census Bureau's two-digit
+# state and five-digit county FIPS code list.
+#
+# Source: https://transition.fcc.gov/oet/info/maps/census/fips/fips.txt
+# Cadence: effectively static (codes change once every several years).
+#
+# This schema describes U.S. states and counties as `location` entities
+# identified by their FIPS strong IDs, along with a containment
+# relationship from each county to its parent state.
+name: "fips"
+description: "U.S. state and county Federal Information Processing Standard (FIPS) codes from the FCC mirror of the Census Bureau list, modelled as `location` entities with FIPS strong IDs"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - name: "location"
+    description: "A specific named geographic location such as a city, country, region, or landmark"
+    display_name: "Location"
+    mergeability: not_mergeable
+    strong_id_properties: ["fips_state", "fips_county"]
+    examples: ["New York City", "San Francisco", "North America", "Bakery Square"]
+    passive: true
+
+properties:
+  - name: "fips_state"
+    type: string
+    description: "Two-digit Federal Information Processing Standard code that uniquely identifies a U.S. state or the District of Columbia"
+    display_name: "State FIPS Code"
+    mergeability: not_mergeable
+    domain_flavors: ["location"]
+    examples: ["01", "06", "11", "36"]
+    passive: true
+
+  - name: "fips_county"
+    type: string
+    description: "Five-digit Federal Information Processing Standard code that uniquely identifies a U.S. county or county-equivalent; the leading two digits are the parent state's FIPS code"
+    display_name: "County FIPS Code"
+    mergeability: not_mergeable
+    domain_flavors: ["location"]
+    examples: ["01001", "06037", "22033", "51790"]
+    passive: true
+
+  - name: "administrative_level"
+    namespace: "fips"
+    type: string
+    description: "Granularity of the geographic entity within the U.S. federal hierarchy of states and counties"
+    display_name: "Administrative Level"
+    mergeability: not_mergeable
+    domain_flavors: ["location"]
+    examples: ["state", "county"]
+    passive: true
+
+  - name: "official_name"
+    namespace: "fips"
+    type: string
+    description: "Verbatim place name as published in the FCC mirror of the FIPS code list, with parenthesized historical annotations stripped"
+    display_name: "Official FIPS Name"
+    mergeability: not_mergeable
+    domain_flavors: ["location"]
+    examples: ["ALABAMA", "Autauga County", "Aleutians East Borough", "East Baton Rouge Parish"]
+    passive: true
+
+relationships:
+  - name: "located_in"
+    description: "Administrative territory or location the entity is situated in (Wikidata P131, P276)"
+    display_name: "Located In"
+    mergeability: not_mergeable
+    domain_flavors: ["location"]
+    target_flavors: ["location"]
+    examples: ["Autauga County is located in Alabama", "Los Angeles County is located in California"]
+    passive: true