@yottagraph-app/aether-instructions 1.1.7 → 1.1.9

package/commands/build_my_app.md

@@ -73,10 +73,10 @@ Then read these files to understand what's available:
 1. `DESIGN.md` -- project vision and current status
 2. `broadchurch.yaml` -- project config (name, gateway URL, etc.)
 3. **The `api` cursor rule** -- this is critical. It describes the Query Server, the platform's primary data source. Build against platform APIs, not external sources.
-4. The **elemental-api skill docs** in `skills/elemental-api/` -- start with `SKILL.md` for API overview, then `entities.md`, `schema.md`, etc.
+4. **`.cursor/skills/`** — Each subdirectory is one skill. List them, open each skill’s entry (usually `SKILL.md`) and follow its structure to learn what is documented (APIs, schemas, helpers, etc.).
 5. `.cursor/rules/` -- scan rule names to know what other patterns are available
 
-**Important: Use the platform's data.** This app runs on the Lovelace platform, which provides a Query Server with entities, news, filings, sentiment, relationships, events, and more. Read the `api` rule and the skill docs to understand what data is available. Use `getSchema()` to discover entity types and properties at runtime.
+**Important: Use the platform's data.** This app runs on the Lovelace platform, which provides a Query Server with entities, news, filings, sentiment, relationships, events, and more. Read the `api` rule and the skills under `.cursor/skills/` to understand what data is available. Use `getSchema()` to discover entity types and properties at runtime.
 
 Key capabilities:
 

package/commands/update_instructions.md

@@ -10,12 +10,13 @@ This command downloads the latest instructions package and extracts it to your `
 
 1. Downloads the latest `@yottagraph-app/aether-instructions` package
 2. Deletes files listed in the existing manifest
-3. Cleans up any legacy `aether_*` prefixed files from older versions
-4. Extracts fresh files from the package
-5. Writes a new manifest
-6. Commits the changes
+3. Extracts fresh files from the package
+4. Writes a new manifest
+5. Commits the changes
 
-**Your files are safe:** Only files listed in the manifest are touched during updates. If you've created your own rules or commands, they won't be modified.
+**Your files are safe:** Only paths listed in the manifest are removed before reinstall. Other files under `.cursor/` are left alone.
+
+**Shell compatibility:** Run the bash snippets below with **`bash`**, not bare `zsh`. An **empty line** in the manifest can make `rm -rf ".cursor/$rel"` delete **all of `.cursor/`** — Step 4 skips blank lines to avoid that.
 
 ---
 
@@ -70,24 +71,17 @@ The extracted content is in `$TEMP_DIR/package/`.
 
 ## Step 4: Delete Previously Installed Files
 
-Read the manifest and delete listed files:
+Read the manifest and delete listed paths. **Skip blank lines** — an empty `rel` would run `rm -rf ".cursor/"` and wipe the whole directory.
 
 ```bash
 if [ -f .cursor/.aether-instructions-manifest ]; then
-  while IFS= read -r rel; do
+  while IFS= read -r rel || [ -n "$rel" ]; do
+    [ -z "$rel" ] && continue
     rm -rf ".cursor/$rel"
   done < .cursor/.aether-instructions-manifest
 fi
 ```
 
-Also clean up legacy `aether_*` files from older package versions:
-
-```bash
-rm -f .cursor/rules/aether_*.mdc
-rm -f .cursor/commands/aether_*.md
-rm -rf .cursor/skills/aether_*/
-```
-
 ---
 
 ## Step 5: Copy New Files
@@ -110,16 +104,18 @@ cp -r "$TEMP_DIR/package/skills/"* .cursor/skills/ 2>/dev/null || true
 
 ## Step 6: Write Manifest and Version Marker
 
-Build a manifest of all installed files (one relative path per line):
+Build a manifest of all installed files (one relative path per line). **Do not** build a string with a leading `\n` — that writes a blank first line and breaks Step 4. Prefer one `echo` per line:
 
 ```bash
-MANIFEST=""
-for f in .cursor/rules/*.mdc; do [ -f "$f" ] && MANIFEST="$MANIFEST\nrules/$(basename "$f")"; done
-for f in .cursor/commands/*.md; do [ -f "$f" ] && MANIFEST="$MANIFEST\ncommands/$(basename "$f")"; done
-for d in .cursor/skills/*/; do [ -d "$d" ] && MANIFEST="$MANIFEST\nskills/$(basename "$d")"; done
-echo -e "$MANIFEST" > .cursor/.aether-instructions-manifest
+{
+  for f in .cursor/rules/*.mdc; do [ -f "$f" ] && echo "rules/$(basename "$f")"; done
+  for f in .cursor/commands/*.md; do [ -f "$f" ] && echo "commands/$(basename "$f")"; done
+  for d in .cursor/skills/*/; do [ -d "$d" ] && echo "skills/$(basename "$d")"; done
+} > .cursor/.aether-instructions-manifest
 ```
 
+If the repo uses **bash** for this loop and a glob might match nothing, run `shopt -s nullglob` first so the loops don’t treat `*.mdc` as a literal filename.
+
 Write the version marker:
 
 ```bash
@@ -161,13 +157,16 @@ Report to user:
 
 ## Step 9: Commit Changes
 
-Commit the updated instruction files:
+Commit the updated instruction files. A root `.gitignore` rule like `skills/` can **ignore** `.cursor/skills/`; if `git add .cursor/skills/` reports ignored paths, force-add:
 
 ```bash
-git add .cursor/rules/ .cursor/commands/ .cursor/skills/ .cursor/.aether-instructions-version .cursor/.aether-instructions-manifest
+git add .cursor/rules/ .cursor/commands/ .cursor/.aether-instructions-version .cursor/.aether-instructions-manifest
+git add -f .cursor/skills/
 git commit -m "Update instructions to vX.Y.Z"
 ```
 
+Use the repo’s commit convention if applicable (e.g. `[Agent commit] Update instructions to vX.Y.Z`).
+
 > Changes committed. Your instructions are now up to date.
 
 ---
@@ -193,3 +192,11 @@ If you need to modify a package-provided file:
 1. Edit it directly — your changes will persist until the next update
 2. To preserve changes across updates, copy it to a new name first
 3. Remove the original's entry from `.cursor/.aether-instructions-manifest` so it won't be deleted on update
+
+### Blank line in manifest deleted `.cursor/`
+
+Regenerate the manifest with Step 6 (echo-per-line form). Ensure Step 4 skips empty lines.
+
+### `git add` says `.cursor/skills` is ignored
+
+Use `git add -f .cursor/skills/` as in Step 9, or narrow `.gitignore` so `skills/` only ignores the project `skills/` folder (e.g. `/skills/` at repo root) instead of every `skills` path.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.7",
+    "version": "1.1.9",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/aether.mdc

@@ -8,7 +8,7 @@ alwaysApply: true
 
 **Structure:** `pages/` (file-based routing), `components/`, `composables/`, `server/api/`, `agents/` (Python ADK), `mcp-servers/` (Python FastMCP).
 
-**Data:** The Query Server (Elemental API) is the primary data source -- entities, news, filings, sentiment, relationships, events. Use `useElementalClient()` from `@yottagraph-app/elemental-api/client`. Do NOT call external APIs for data the platform provides. Discovery-first: use `getSchema()` to discover entity types and properties at runtime. Skill docs in `skills/elemental-api/` (run `npm install` if empty). Lovelace MCP servers may also be configured (see `api` rule) but are optional — check your tool list before assuming they're available.
+**Data:** The Query Server (Elemental API) is the primary data source -- entities, news, filings, sentiment, relationships, events. Use `useElementalClient()` from `@yottagraph-app/elemental-api/client`. Do NOT call external APIs for data the platform provides. Discovery-first: use `getSchema()` to discover entity types and properties at runtime. Skill docs: `skills/elemental-api/` (API endpoints) and `skills/data-model/` (Lovelace entity types, properties, relationships, YAML schemas per fetch source; `SKILL.md` first). Run `npm install` if those directories are empty. Lovelace MCP servers may also be configured (see `api` rule) but are optional — check your tool list before assuming they're available.
 
 **Storage:** KV (Upstash Redis) for preferences and lightweight state via `Pref<T>` from `usePrefsStore()`. Supabase for relational data if connected (check `.env`).
 

package/rules/api.mdc

@@ -16,21 +16,16 @@ regularly — use the discovery-first pattern to find what's available.
 
 ## Skill Documentation
 
-For full endpoint documentation, read the **elemental-api skill** in
-`skills/elemental-api/`. Start with `SKILL.md`, then `overview.md`.
-These files are copied from `@yottagraph-app/elemental-api-skill` during
-`npm install` (postinstall step) — if the directory is empty, run
-`npm install` first. The skill docs contain detailed response shapes and
-edge cases that go beyond this rule's quick reference — **run `npm install`
-early** to make them available during initial exploration.
-
-Key files:
-- `entities.md` — entity search, details, and properties
-- `find.md` — expression language for searching by type, property, and relationships
-- `schema.md` — entity types (flavors), properties (PIDs), and schema endpoints
-- `relationships.md` — entity connections
-- `events.md` — events involving entities
-- `articles.md` — news mentions and article content
+For endpoint reference, response shapes, and edge cases, **read the
+elemental-api skill** in `skills/elemental-api/` (start with `SKILL.md` and
+follow the skill’s own structure). Files are copied from
+`@yottagraph-app/elemental-api-skill` during `npm install` (see
+`skill-packages.json`); if the directory is empty, run `npm install` first —
+**run it early** during initial exploration so the skill is available.
+
+## Data model skill
+
+For Lovelace **entity types, properties, relationships, and per-source schemas** (EDGAR, FRED, FDIC, etc.), read the **data-model skill** in `skills/data-model/`. Start with `SKILL.md`, then `overview.md` and the source-specific folders. These files are copied from `@yottagraph-app/data-model-skill` during `npm install` (same postinstall; both skills are listed in `skill-packages.json`).
 
 ## Client Usage
 

package/skills/data-model/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: data-model
+description: Understand the Lovelace data model - entity types, properties, relationships, and schemas from fetch sources like EDGAR, FRED, FDIC, and more.
+---
+
+# Data Model Skill
+
+This skill provides documentation for the Lovelace data model, describing the entity types, properties, and relationships that each fetch source contributes to the knowledge graph.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Understand what entity types exist (organizations, people, filings, etc.)
+- Know what properties are available on entities
+- Understand relationships between entity types
+- Look up the schema definition for a data source
+
+## Quick Start
+
+1. **Identify the source**: Determine which data source is relevant (EDGAR for SEC filings, FRED for economic data, etc.)
+2. **Read the DATA_DICTIONARY.md**: Get human-readable documentation of entities, properties, and relationships
+3. **Check schema.yaml**: For machine-readable schema definitions including flavors, properties, and extraction rules
+
+## Available Sources
+
+| Source | Description | Files |
+|--------|-------------|-------|
+| [edgar](edgar/) | SEC EDGAR filings - 10-K, 10-Q, 8-K, ownership forms, institutional holdings | DATA_DICTIONARY.md, schema.yaml |
+| [fdic](fdic/) | FDIC BankFind Suite - insured institutions, branch data, failures | DATA_DICTIONARY.md, schema.yaml |
+| [fred](fred/) | Federal Reserve Economic Data - GDP, employment, inflation, rates | DATA_DICTIONARY.md, schema.yaml |
+| [gleif](gleif/) | Global Legal Entity Identifier Foundation - LEI records, corporate ownership | DATA_DICTIONARY.md, schema.yaml |
+| [newsdata](newsdata/) | News articles and press releases with LLM extraction | schema.yaml |
+| [polymarket](polymarket/) | Polymarket prediction markets via Gamma API | DATA_DICTIONARY.md, schema.yaml |
+| [sanctions](sanctions/) | OpenSanctions - OFAC, EU, UN, HM Treasury sanctions lists | DATA_DICTIONARY.md, schema.yaml |
+| [stocks](stocks/) | US equity OHLCV price data from Alpha Vantage (NYSE, NASDAQ, AMEX) | DATA_DICTIONARY.md, schema.yaml |
+| [wikipedia](wikipedia/) | People, locations, and organizations from English Wikipedia | DATA_DICTIONARY.md, schema.yaml |
+
+## File Types
+
+### DATA_DICTIONARY.md
+
+Human-readable documentation containing:
+- **Source Overview**: What the source is and how data flows through the pipeline
+- **Entity Types**: What flavors (entity types) this source creates, with primary keys and resolver behavior
+- **Properties**: Field definitions with examples and derivation notes
+- **Relationships**: How entities connect to each other
+
+### schema.yaml
+
+Machine-readable schema definition containing:
+- **flavors**: Entity type definitions with mergeability and strong ID properties
+- **properties**: Field definitions with types, descriptions, and domain flavors
+- **relationships**: Link definitions with domain and target flavors
+- **extraction**: Whether the schema is open or closed for each category
+
+## See Also
+
+- [overview.md](overview.md) - Core concepts and how to navigate the documentation

package/skills/data-model/edgar/DATA_DICTIONARY.md

@@ -0,0 +1,306 @@
+# Data Dictionary: EDGAR
+
+## Source Overview
+
+SEC EDGAR (Electronic Data Gathering, Analysis, and Retrieval) filings via two pipelines:
+- **Company facts / XBRL**: structured financial data from `companyfacts.zip` and `submissions.zip` bulk APIs
+- **Form parsing**: regulatory forms (10-K, 10-Q, 20-F, 8-K, Form 3/4, SC 13D/G, 13F-HR, DEF 14A) parsed from HTML, XML, and SGML documents
+
+Financial figures from XBRL may be computed fallbacks when a company does not file the authoritative tag. Not all companies report all fields.
+
+| Pipeline | `Record.Source` |
+|----------|----------------|
+| Company facts / XBRL / submissions | `edgar` |
+| 10-K annual report | `edgar_10k` |
+| 10-Q quarterly report | `edgar_10q` |
+| 20-F foreign issuer annual report | `edgar_20f` |
+| 8-K current report | `edgar_8k` |
+| Form 3 initial ownership | `edgar_3` |
+| Form 4 ownership changes | `edgar_4` |
+| SC 13D beneficial ownership (active) | `edgar_sc_13d` |
+| SC 13G beneficial ownership (passive) | `edgar_sc_13g` |
+| Co-registrant / subsidiary | `edgar_coregistrant` |
+| 13F-HR institutional holdings | `edgar_13fhr` |
+| DEF 14A proxy statement | `edgar_def_14a` |
+
+---
+
+## Entity Types
+
+### `organization`
+
+A public company, institutional investor, or corporate filer registered with the SEC.
+
+- Primary key: `company_cik` (10-digit zero-padded CIK)
+- Entity resolver: named entity. Strong ID = `company_cik`. Disambiguation via company name, city, state, SIC description, EIN. Ticker and former names as aliases.
+- Financial metrics from XBRL are dual-homed on both the filing document and the organization, with a `filing_period` attribute (`FY`, `Q1`, `Q2`, `Q3`) to distinguish annual from quarterly values.
+
+### SEC Filing Types (namespace: `sec`)
+
+Each SEC form type is a separate flavor, namespaced under `sec`. All share the same strong ID (`accession_number`) and are not mergeable.
+
+| Flavor | Display Name | Description |
+|--------|-------------|-------------|
+| `sec::10_k` | 10-K | Annual report |
+| `sec::10_q` | 10-Q | Quarterly report |
+| `sec::20_f` | 20-F | Foreign private issuer annual report |
+| `sec::8_k` | 8-K | Current report (material events) |
+| `sec::form_3` | Form 3 | Initial statement of beneficial ownership |
+| `sec::form_4` | Form 4 | Statement of changes in beneficial ownership |
+| `sec::sc_13d` | SC 13D | Beneficial ownership report (activist) |
+| `sec::sc_13g` | SC 13G | Beneficial ownership report (passive) |
+| `sec::13f_hr` | 13F-HR | Institutional investment manager holdings |
+| `sec::def_14a` | DEF 14A | Definitive proxy statement |
+
+Sub-records (8-K events, Form 4 transactions, Form 3 holdings) use their parent filing's flavor.
+
+### `person`
+
+A corporate insider (officer, director, or significant owner) from Form 3 or Form 4.
+
+- Primary key: `person_cik` when available; otherwise named entity resolution.
+- Entity resolver: named entity, mergeable. Strong ID = `person_cik` when present.
+
+### `financial_instrument`
+
+A tradeable security identified by CUSIP, from 13F-HR filings.
+
+- Primary key: `cusip_number`
+- Entity resolver: named entity. Strong ID = `cusip_number`.
+
+---
+
+## Properties
+
+### Organization Properties
+
+#### Identity and Registration (source: `edgar`)
+
+Data source: `https://data.sec.gov/submissions/CIK{cik}.json`
+
+* `company_cik`
+  * Definition: SEC Central Index Key, 10-digit zero-padded.
+  * Examples: `"0000320193"` (Apple), `"0000789019"` (Microsoft)
+  * Derivation: `cik` field from submissions API, zero-padded.
+
+* `ticker`
+  * Definition: Primary stock ticker symbol. Only set for listed companies.
+  * Examples: `"AAPL"`, `"MSFT"`, `"BRK-A"`
+  * Derivation: first entry from `tickers` array.
+
+* `exchange`
+  * Definition: Securities exchange listing.
+  * Examples: `"Nasdaq"`, `"NYSE"`, `"OTC"`
+  * Derivation: first entry from `exchanges` array.
+
+* `sic_code`
+  * Definition: Four-digit Standard Industrial Classification code.
+  * Examples: `"3571"`, `"6022"`
+  * Derivation: `sic` field.
+
+* `sic_description`
+  * Definition: Human-readable SIC code description.
+  * Examples: `"Electronic Computers"`, `"State Commercial Banks"`
+  * Derivation: `sicDescription` field.
+
+* `state_of_incorporation`
+  * Definition: Two-letter US state or country code of incorporation.
+  * Examples: `"CA"`, `"DE"`, `"NY"`
+  * Derivation: `stateOfIncorporation` field.
+
+* `fiscal_year_end`
+  * Definition: Fiscal year end as MMDD string.
+  * Examples: `"0930"`, `"1231"`
+  * Derivation: `fiscalYearEnd` field.
+
+* `ein`
+  * Definition: IRS Employer Identification Number (9 digits). Known bogus EINs filtered.
+  * Example: `"942404110"`
+  * Derivation: `ein` field, validated against bogus list.
+
+* `business_phone`
+  * Definition: Primary business phone number.
+  * Example: `"4089961010"`
+  * Derivation: `addresses.business.phone` field.
+
+* `filer_category`
+  * Definition: SEC filer size category.
+  * Examples: `"Large accelerated filer"`, `"Non-accelerated filer"`
+  * Derivation: `category` field.
+
+* `physical_address`
+  * Definition: Business address as formatted string.
+  * Example: `"One Apple Park Way, Cupertino, CA 95014"`
+  * Derivation: `addresses.business` fields concatenated.
+
+* `mailing_address`
+  * Definition: Mailing address as formatted string. May differ from physical address.
+  * Derivation: `addresses.mailing` fields concatenated.
+
+* `former_name`
+  * Definition: Previous legal name. One value per entry in former names list.
+  * Example: `"Apple Computer, Inc."`
+  * Derivation: `formerNames` array. Also used as aliases for entity resolution.
+
+#### Financial Data (source: `edgar_10k`, `edgar_10q`, `edgar_20f`)
+
+Data source: iXBRL inline financial statements. All values USD unless noted.
+The six core financial properties appear on both the **organization** and its **document** (filing) entity so that revenue/income/balance-sheet values are queryable on the company directly.
+
+* `total_revenue` — Total revenues. Unit: USD. On: organization + document
+* `net_income` — Net income or loss. Unit: USD. On: organization + document
+* `total_assets` — Sum of all balance sheet assets. Unit: USD. On: organization + document
+* `total_liabilities` — Sum of all liabilities. May be computed fallback. Unit: USD. On: organization + document
+* `shareholders_equity` — Total stockholders' equity. Unit: USD. On: organization + document
+* `shares_outstanding` — Common shares outstanding. Unit: shares. On: organization + document
+* `eps_basic` — Basic earnings per share (10-K only). Unit: USD. On: document only
+* `eps_diluted` — Diluted earnings per share (10-K only). Unit: USD. On: document only
+* `entity_shell_company` — Whether the entity is a shell company. Values: `"true"`, `"false"`. On: organization only
+* `reporting_currency` — ISO 4217 currency code (20-F only). Examples: `"JPY"`, `"EUR"`. On: document only
+* `country_of_incorporation` — Country of incorporation (20-F only). Examples: `"Japan"`, `"Israel"`. On: document only
+
+#### 8-K Corporate Events (source: `edgar_8k`)
+
+Data source: 8-K current report filings. Properties on document sub-records.
+
+* `form_8k_event` — Snake_case event identifier. Examples: `"material_agreement"`, `"officer_director_change"`
+* `form_8k_item_code` — Raw SEC item number. Examples: `"1.01"`, `"5.02"`
+* `category` — Sub-classification of Item 8.01 Other Events. Examples: `"cybersecurity_incident"`
+
+#### Beneficial Ownership (source: `edgar_sc_13d`, `edgar_sc_13g`)
+
+Data source: SC 13D/G XML filings. Properties on the filer organization.
+
+* `owns_stake_in` — Relationship: filer → issuer whose shares are held
+* `group_shares_declared` — Total shares owned by the filing group. Unit: shares
+* `group_ownership_percent` — Percentage of share class owned by the group
+* `is_group_filing` — Float: `1.0` = group filing, `0.0` = single filer
+* `shares_declared` — Shares by individual group member. Unit: shares
+* `ownership_percent` — Percentage by individual member or SC 13G filer
+* `investment_purpose` — Stated purpose from Item 4. Examples: `"Investment"`, `"Strategic investment"`
+* `is_passive_investor` — Always `1.0` on SC 13G records
+* `aggregate_amount_beneficially_owned` — Total shares beneficially owned. Unit: shares
+* `sole_voting_power` / `shared_voting_power` — Sole/shared voting authority. Unit: shares
+* `sole_dispositive_power` / `shared_dispositive_power` — Sole/shared dispositive power. Unit: shares
+* `type_of_reporting_person` — SEC entity code. Examples: `"CO"`, `"IN"`, `"IA"`
+* `citizenship_or_state_of_organization` — Jurisdiction. Examples: `"Delaware"`, `"Cayman Islands"`
+* `source_of_funds` — Acquisition fund source. Examples: `"WC"`, `"OO"`, `"BK"`
+* `cusip_number` — CUSIP of the subject securities. Example: `"037833100"`
+
+#### Subsidiary Relationships (source: `edgar_coregistrant`, `edgar_10k`)
+
+Data source: co-registrant entries and EX-21 exhibit subsidiary tables.
+
+* `has_subsidiary` — Relationship: parent → subsidiary
+* `is_part_of` — Relationship: subsidiary → parent
+* `citizenship_or_state_of_organization` — Subsidiary jurisdiction (EX-21 only)
+
+### Document Properties
+
+#### Filing Metadata (all pipelines)
+
+* `accession_number` — SEC accession number. Example: `"0000320193-24-000123"`
+* `form_type` — Normalized form type. Examples: `"10-K"`, `"SC 13D"`, `"4"`
+* `filing_date` — Submission date (YYYY-MM-DD)
+* `issued_by` — Relationship: filing → company the filing pertains to. For annual/quarterly/current reports, this is the filer. For ownership forms (Form 3/4, SC 13D/G), this is the issuer company whose securities are the subject of the filing.
+  * Derivation (ownership forms): XML `<issuerCik>` / `<issuerName>` elements, with fallback to SEC submissions API index metadata for Forms 3/4/5 or the SGML header `<SUBJECT-COMPANY>` section for SC 13D/G. Omitted when no reliable issuer data is available.
+* `refers_to` — Relationship: filing → company the document is about. Same derivation as `issued_by` for ownership forms.
+
+#### XBRL Financial Facts (source: `edgar`)
+
+Data source: `https://data.sec.gov/api/xbrl/companyfacts/CIK{cik}.json`. ~75 XBRL properties tracked across US-GAAP, DEI, and IFRS taxonomies. Atom timestamp = XBRL period end date, not filing date. Computed fallbacks carry `"Computed from ..."` citation.
+
+Key US-GAAP properties: `us_gaap:assets`, `us_gaap:liabilities`, `us_gaap:stockholders_equity`, `us_gaap:revenues`, `us_gaap:net_income_loss`, `us_gaap:operating_income_loss`, `us_gaap:operating_cash_flow`, `us_gaap:investing_cash_flow`, `us_gaap:financing_cash_flow`, `us_gaap:gross_profit`, `us_gaap:long_term_debt`, `us_gaap:common_shares_outstanding`, `us_gaap:goodwill`, `us_gaap:pp_and_e_net`, `us_gaap:operating_expenses`, `us_gaap:sg_and_a`, `us_gaap:research_and_development`, `us_gaap:income_tax_expense`, `us_gaap:eps_basic_xbrl`, `us_gaap:eps_diluted_xbrl`, `us_gaap:weighted_avg_shares_basic`, `us_gaap:weighted_avg_shares_diluted`, `us_gaap:share_repurchases`, `us_gaap:dividends_common`, `us_gaap:debt_repayments`, `us_gaap:acquisition_payments`, `us_gaap:comprehensive_income`, `us_gaap:asset_impairment`, `us_gaap:goodwill_impairment`, `us_gaap:number_of_segments`.
+
+DEI properties: `dei:public_float`, `dei:common_shares_outstanding`, `dei:number_of_employees`.
+
+IFRS properties (foreign private issuers): `ifrs:assets`, `ifrs:cash_and_cash_equivalents`, `ifrs:equity`, `ifrs:profit_loss`, `ifrs:operating_cash_flow`, `ifrs:current_assets`, `ifrs:current_liabilities`, `ifrs:liabilities`, `ifrs:revenue`.
+
+Full mapping in `XBRLConceptMappings`.
+
+#### SC 13D on Document (source: `edgar_sc_13d`)
+
+* `filer` — Relationship: document → beneficial owner
+* `group_member` — Relationship: document → group members (excluding primary filer)
+* `group_shares_declared`, `group_ownership_percent`, `is_group_filing` — Filing-level ownership facts
+
+### Person Properties
+
+#### Insider Identity (source: `edgar_3`, `edgar_4`)
+
+Data source: Form 3/4 XML.
+
+* `person_cik` — SEC CIK for the reporting person (10-digit zero-padded). From `<rptOwnerCik>`.
+* `job_title` — Officer title. Examples: `"Chief Executive Officer"`, `"Director"`. From `<officerTitle>`.
+* `is_officer` — Relationship: person → organization (when `<isOfficer>1`)
+* `is_director` — Relationship: person → organization (when `<isDirector>1`)
+* `is_ten_percent_owner` — Relationship: person → organization (when `<isTenPercentOwner>1`)
+* `works_at` — Relationship: person → issuer company
+* `filing_reference` — Relationship: person → source Form 3/4 document
+
+#### Form 4 Transactions (source: `edgar_4`)
+
+Properties on document sub-records, one per transaction.
+
+* `transaction_type` — Human-readable code description. Examples: `"Open market or private purchase"`, `"Grant, award, or other acquisition"`
+* `transaction_date` — Transaction date (YYYY-MM-DD)
+* `acquired_disposed_code` — `"A"` (acquired) or `"D"` (disposed)
+* `security_type` — Security class. Examples: `"Common Stock"`, `"Stock Option (Right to Buy)"`
+* `shares_transacted` — Shares transferred. Unit: shares
+* `price_per_share` — Transaction price. Unit: USD
+* `shares_owned_after` — Post-transaction shares. Unit: shares
+* `exercise_price` — Derivative exercise price (USD, derivatives only)
+* `direct_or_indirect_ownership` — `"Direct"` or `"Indirect"`
+* `is_10b5_1_plan` — `"true"` when under a Rule 10b5-1 plan
+
+#### DEF 14A Proxy (source: `edgar_def_14a`)
+
+* `board_committee` — Committee membership. Examples: `"Audit"`, `"Compensation"`
+* `is_independent` — Independence classification. Values: `"true"`, `"false"`
+* `director_since` — Year. Example: `"2018"`
+* `total_compensation` — Summary Compensation Table total. Unit: USD
+* `board_size` — Number of directors (also on document)
+* `compares_to` — Relationship: document → peer companies
+* `auditor` — Accounting firm name. Example: `"Ernst & Young LLP"`
+* `audit_fees` — Auditor fees. Unit: USD
+
+### Financial Instrument Properties
+
+#### 13F-HR Holdings (source: `edgar_13fhr`)
+
+Data source: 13F-HR XML information table.
+
+* `cusip_number` — CUSIP identifier. Example: `"037833100"`
+* `security_type` — Security class. Examples: `"COM"`, `"SHS"`, `"COM CL A"`
+* `position_value` — Market value (USD)
+* `shares_held` — Shares or principal amount held
+* `instrument_type` — `"SH"` (shares) or `"PRN"` (principal amount)
+* `put_call` — `"PUT"`, `"CALL"`, or empty for equity
+* `voting_authority_sole` / `voting_authority_shared` / `voting_authority_none` — Voting authority breakdown. Unit: shares
+* `investment_discretion` — `"SOLE"`, `"DFND"`, or `"OTR"` (on organization)
+* `holds_position` — Relationship: investment manager → financial instrument
+
+---
+
+## Entity Relationships
+
+```
+organization         ──[filed]────────────────────→ document
+organization         ──[filing_reference]─────────→ document
+organization         ──[owns_stake_in]────────────→ organization    (SC 13D/G)
+organization         ──[has_subsidiary]───────────→ organization    (co-registrant, EX-21)
+organization         ──[is_part_of]───────────────→ organization    (subsidiary → parent)
+organization         ──[holds_position]───────────→ financial_instrument (13F-HR)
+document             ──[issued_by]────────────────→ organization
+document             ──[refers_to]────────────────→ organization
+document             ──[filer]────────────────────→ organization    (SC 13D/G)
+document             ──[group_member]─────────────→ organization    (SC 13D)
+document             ──[compares_to]──────────────→ organization    (DEF 14A)
+document             ──[filed]────────────────────→ document        (sub-record → parent)
+person               ──[is_officer]───────────────→ organization
+person               ──[is_director]──────────────→ organization
+person               ──[is_ten_percent_owner]─────→ organization
+person               ──[works_at]─────────────────→ organization
+person               ──[filing_reference]─────────→ document
+financial_instrument ──[filing_reference]─────────→ document
+```