# Taxonomy Pack Authoring

## Pack Catalog

Active non-core fiscal packs:

- `bank_lender`
- `insurance`
- `reit_real_estate`
- `broker_asset_manager`
- `agriculture`
- `contractors_construction`
- `contractors_federal_government`
- `development_stage`
- `entertainment_broadcasters`
- `entertainment_cable_television`
- `entertainment_casinos`
- `entertainment_films`
- `entertainment_music`
- `extractive_mining`
- `mortgage_banking`
- `title_plant`
- `franchisors`
- `not_for_profit`
- `plan_defined_benefit`
- `plan_defined_contribution`
- `plan_health_welfare`
- `real_estate_general`
- `real_estate_common_interest`
- `real_estate_retail_land`
- `real_estate_time_sharing`
- `software`
- `steamship`

## Required Files

Every non-core pack needs three files:

- `rust/taxonomy/fiscal/v1/<pack>.surface.json`
- `rust/taxonomy/fiscal/v1/<pack>.income-bridge.json`
- `rust/taxonomy/fiscal/v1/kpis/<pack>.kpis.json`

Pack-specific `*.computed.json` files are optional. If a pack does not define one, the runtime falls back to `core.computed.json`.

## Surface Rules

- Use snake_case `surface_key` values.
- Normalize categories to the existing runtime vocabulary such as `current_assets`, `noncurrent_assets`, `current_liabilities`, `noncurrent_liabilities`, `equity`, `surface`, and `derived`.
- Prefer canonical `us-gaap:` concept names in both `allowed_source_concepts` and `allowed_authoritative_concepts`.
- Use `aggregate_children` plus `group_all_children` for rows expected to absorb child detail.
- Use `direct_only` for balance-sheet totals such as `total_assets`, `total_liabilities`, and `total_equity`.
- Keep labels in repo house style and American spelling.

## Bridge Rules

- Start from `core.income-bridge.json` and override only rows whose economics differ for the pack.
- Override `revenue` for every non-core pack.
- Only derive `gross_profit` for packs with a real cost-of-revenue pair.
- Mark `gross_profit` as `not_meaningful` when the pack does not present a stable gross-profit concept.
- Override `operating_expenses` only with pack-specific expense buckets.
- Use warning codes that match the existing pattern, for example `gross_profit_not_meaningful_<pack>` or `revenue_formula_derived`.

## Classifier Precedence

The runtime classifier is conservative and requires a pack-unique primary concept plus secondary support. Specific overlaps are resolved in this order:

- `contractors_federal_government` over `contractors_construction`
- `mortgage_banking` over `bank_lender`
- `title_plant` over `insurance`
- `real_estate_time_sharing` over `real_estate_retail_land` over `real_estate_common_interest` over `real_estate_general`
- `reit_real_estate` remains separate and should win only on lease / investment-property signatures

If a filing is ambiguous after scoring, it stays on `core`.