Automate issuer overlay creation from ticker searches

docs/architecture/financial-surfaces.md

@@ -45,6 +45,15 @@ As of Issue #26, the financial statement mapping architecture follows a **Rust-f
 
 ## Source of Truth
 
+## Statement Admission
+
+Primary statements are admitted conservatively:
+
+- presentation-role classification is authoritative
+- no-role fallback only admits concepts that match a primary statement taxonomy surface
+- disclosure-only concepts stay in raw persisted facts/concepts and must not appear as primary statement residuals
+- `equity_statement` is a first-class surfaced statement, but it is faithful-first and only has minimal standardized coverage in this pass
+
 ### Authoritative Sources (Edit These)
 1. **`rust/taxonomy/fiscal/v1/core.surface.json`**
    - Defines all surface keys, labels, categories, orders, and formulas
@@ -138,6 +147,14 @@ See `rust/taxonomy/fiscal/v1/core.surface.json` for complete list.
 ### Cash Flow Statement
 See `rust/taxonomy/fiscal/v1/core.surface.json` for complete list.
 
+### Stockholders' Equity Statement
+
+`equity_statement` is exposed in the API/UI as a primary statement surface.
+
+- faithful rows come from snapshot `statement_rows.equity`
+- standardized rows currently cover only a minimal canonical set
+- disclosure-style equity concepts are intentionally excluded from primary statement admission
+
 ## Related Files
 - `rust/fiscal-xbrl-core/src/surface_mapper.rs` - Surface resolution logic
 - `rust/fiscal-xbrl-core/src/taxonomy_loader.rs` - JSON loading

docs/architecture/taxonomy.md

@@ -10,7 +10,7 @@ The taxonomy system defines all financial surfaces, computed ratios, and KPIs us
 ┌─────────────────────────────────────────────────────────────────┐
 │                     rust/taxonomy/fiscal/v1/                     │
 │                                                                  │
-│  core.surface.json        - Income/Balance/Cash Flow surfaces    │
+│  core.surface.json        - Income/Balance/Cash Flow/Equity      │
 │  core.computed.json       - Ratio definitions                    │
 │  core.kpis.json           - Sector-specific KPIs                 │
 │  core.income-bridge.json  - Income statement mapping rules       │
@@ -130,7 +130,7 @@ Generated TypeScript statement catalogs are built from the deduped union of core
 | Field                     | Type     | Description                                                                                |
 | ------------------------- | -------- | ------------------------------------------------------------------------------------------ |
 | `surface_key`             | string   | Unique identifier (snake_case)                                                             |
-| `statement`               | enum     | `income`, `balance`, `cash_flow`, `equity`, `comprehensive_income`                         |
+| `statement`               | enum     | `income`, `balance`, `cash_flow`, `equity`, `comprehensive_income`, `disclosure`           |
 | `label`                   | string   | Human-readable label                                                                       |
 | `category`                | string   | Grouping category                                                                          |
 | `order`                   | number   | Display order                                                                              |
@@ -215,6 +215,29 @@ This ensures consistency across packs while allowing sector-specific income stat
 
 Auto-classification remains conservative. Pack selection uses concept and role scoring, then falls back to `core` when the top match is weak or ambiguous.
 
+## Issuer Overlay Automation
+
+Issuer overlays now support a runtime, database-backed path in addition to checked-in JSON files. Explicit user ticker submits enqueue filing sync through `POST /api/tickers/ensure`; the sync task hydrates filings with the current overlay revision, generates additive issuer mappings from residual extension concepts, and immediately rehydrates recent filings when a new overlay revision is published.
+
+Automation is intentionally conservative:
+
+- it only extends existing canonical surfaces
+- it does not synthesize new surfaces
+- it does not auto-delete prior mappings
+
+Runtime overlay merge order is:
+
+1. pack primary/disclosure
+2. core primary/disclosure
+3. static issuer overlay file
+4. runtime issuer overlay
+
+No-role statement admission is taxonomy-aware:
+
+- primary statement admission is allowed only when a concept matches a primary statement surface
+- disclosure-only concepts are excluded from surfaced primary statements
+- explicit overlap handling exists for shared balance/equity concepts such as `StockholdersEquity` and `LiabilitiesAndStockholdersEquity`
+
 ## Build Pipeline
 
 ```bash