@yottagraph-app/aether-instructions 1.1.23 → 1.1.25

package/commands/update_branding.md

@@ -1,123 +1,71 @@
 # Update Branding
 
-Refresh the Lovelace Brand R2 files from the canonical source repository.
+Sync the project's branding implementation with the latest Lovelace branding skill guidelines.
 
 ## Overview
 
-Aether's branding files are wholesale copies from the `moongoose/ui/news-ui` directory of the Lovelace repo. This command copies the latest versions and checks for new dependencies.
-
-**Do not hardcode any local paths.** Always ask the user for the Lovelace repo location.
+The `lovelace-branding` skill (`skills/lovelace-branding/`) is the single source of truth for Lovelace brand identity. This command reviews the project's branding implementation files and updates them to align with the skill.
 
 ---
 
-## Step 1: Ask for the Lovelace Repo Path
-
-```
-AskQuestion({
-  title: "Lovelace Repository Path",
-  questions: [
-    {
-      id: "repo-path",
-      prompt: "Where is your local clone of the Lovelace repository?",
-      options: [
-        { id: "home-lovelace", label: "~/lovelace" },
-        { id: "custom", label: "Other location (I'll specify)" }
-      ]
-    }
-  ]
-})
-```
+## Step 1: Read the Branding Skill
 
-If the user selects "Other location", ask them to provide the full path.
-
-Expand `~` to the user's home directory. Store the result as `{repo}`.
+Read the skill starting from `skills/lovelace-branding/SKILL.md`. It contains a file index that will direct you to the relevant reference files.
 
 ---
 
-## Step 2: Validate the Source Path
-
-Confirm the branding source directory exists:
+## Step 2: Review Implementation Files
 
-```bash
-ls {repo}/moongoose/ui/news-ui/BRANDING.md
-```
+Read each of the project's branding implementation files and compare against the skill guidelines:
 
-**If the file does not exist:** Tell the user the path doesn't contain the expected branding files and ask them to double-check. Stop.
+| File                              | What to check                                                                     |
+| --------------------------------- | --------------------------------------------------------------------------------- |
+| `assets/brand-globals.css`        | `:root` CSS variables match the skill's color and typography values               |
+| `assets/fonts.css`                | `@font-face` declarations match the skill's font setup                            |
+| `assets/theme-styles.css`         | Theme utility classes align with the skill's CSS patterns                         |
+| `composables/useLovelaceTheme.ts` | `themeColors` object matches the skill's color palette                            |
+| `composables/useThemeClasses.ts`  | Theme-aware utilities consistent with skill patterns                              |
+| `nuxt.config.ts`                  | Vuetify theme colors match the skill; CSS array includes all branding stylesheets |
 
-Also verify the other expected source files exist:
-
-```bash
-ls {repo}/moongoose/ui/news-ui/composables/useNewsTheme.ts
-ls {repo}/moongoose/ui/news-ui/composables/useThemeClasses.ts
-ls {repo}/moongoose/ui/news-ui/assets/theme-styles.css
-ls {repo}/moongoose/ui/news-ui/assets/fonts.css
-ls {repo}/moongoose/ui/news-ui/public/fonts/README.md
-ls {repo}/moongoose/ui/news-ui/public/LL-logo-full-wht.svg
-```
-
-Report any missing files. If critical files are missing (BRANDING.md, useNewsTheme.ts, theme-styles.css), stop. If optional files are missing (logo, fonts README), warn but continue.
+For each file, note any discrepancies between the current implementation and the skill guidelines.
 
 ---
 
-## Step 3: Copy the Branding Files
+## Step 3: Update Implementation
 
-The base source path is `{repo}/moongoose/ui/news-ui`.
+For each discrepancy found in Step 2, update the project file to align with the skill:
 
-Copy these files to their Aether destinations:
+- **CSS variables**: Update hex values, add missing variables, remove obsolete ones
+- **Color palette**: Update `themeColors` in `useLovelaceTheme.ts` to match
+- **Typography**: Update font families, weights, and fallbacks as specified by the skill
+- **Patterns**: Update theme utility classes to match the skill's CSS patterns
+- **Vuetify theme**: Update `lovelaceDark` theme colors in `nuxt.config.ts` if needed
 
-| Source (relative to base)        | Destination (relative to Aether root) |
-| -------------------------------- | ------------------------------------- |
-| `BRANDING.md`                    | `branding/BRANDING.md`                |
-| `composables/useNewsTheme.ts`    | `composables/useNewsTheme.ts`         |
-| `composables/useThemeClasses.ts` | `composables/useThemeClasses.ts`      |
-| `assets/theme-styles.css`        | `assets/theme-styles.css`             |
-| `assets/fonts.css`               | `assets/fonts.css`                    |
-| `public/fonts/README.md`         | `public/fonts/README.md`              |
-| `public/LL-logo-full-wht.svg`    | `public/LL-logo-full-wht.svg`         |
+If the skill introduces new concepts not yet implemented in the project (new CSS variable namespaces, new utility classes, new patterns), add them.
 
-For `app.vue`, extract only the `<style>` block contents (not the `<style>` tags themselves) and write them to `assets/brand-globals.css`. Read the source `app.vue`, find the content between `<style>` and `</style>`, and overwrite `assets/brand-globals.css` with that content.
+If the project has customizations that intentionally diverge from the skill (e.g., project-specific semantic colors), preserve them but note the divergence.
 
 ---
 
-## Step 4: Dependency Audit
-
-After copying, read through each copied file and check for new references that weren't present before:
+## Step 4: Check Assets
 
-1. **TypeScript imports**: Check `useNewsTheme.ts` and `useThemeClasses.ts` for any new `import` statements referencing files that don't exist in Aether.
+Compare logo and asset files in `public/` against the skill's `assets/` directory (`skills/lovelace-branding/assets/`).
 
-2. **CSS references**: Check `theme-styles.css`, `fonts.css`, and `brand-globals.css` for:
-    - `url()` paths pointing to files not in `public/`
-    - `@import` statements referencing files not in `assets/`
-
-3. **Documentation references**: Check `BRANDING.md` for references to new files (logos, assets, CSS files) that should be copied.
-
-**If new dependencies are found:**
-
-- Static assets (images, SVGs, fonts) -> copy to `public/` in the equivalent subdirectory
-- CSS files -> copy to `assets/`
-- TypeScript/JS files -> copy to `composables/` or the equivalent directory
-- Report what was copied to the user
+- Copy any new or updated SVGs/assets from the skill to `public/`
+- If existing assets differ, update them to the skill's versions
 
 ---
 
-## Step 5: Verify Integration
-
-Check that the adapter (`composables/useCustomTheme.ts`) is still compatible:
-
-1. Read `composables/useNewsTheme.ts` and check what it exports.
-2. Read `composables/useCustomTheme.ts` and confirm it re-exports the expected interface.
-3. If `useNewsTheme.ts` has added new named exports that aren't re-exported by the adapter, tell the user:
-
-> `useNewsTheme.ts` has new exports that aren't exposed through `useCustomTheme.ts`: [list them]. You may want to add these to the adapter if components need them.
-
-4. Check that `nuxt.config.ts` still includes the three CSS files:
+## Step 5: Verify
 
-```typescript
-css: ['~/assets/fonts.css', '~/assets/brand-globals.css', '~/assets/theme-styles.css'],
-```
+1. Confirm `nuxt.config.ts` CSS array still includes all branding stylesheets:
+    ```typescript
+    css: ['~/assets/fonts.css', '~/assets/brand-globals.css', '~/assets/theme-styles.css'];
+    ```
+2. Run `npm run build` to verify no compilation errors
 
 ---
 
 ## Step 6: Commit
 
-Follow the `git-support.mdc` workflow to commit the change.
+Follow the `git-support.mdc` workflow to commit the changes.

package/package.json

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

package/rules/branding.mdc

@@ -3,41 +3,33 @@ description: Apply when working on visual styling, colors, typography, theming,
 alwaysApply: false
 ---
 
-# Lovelace Brand R2
+# Lovelace Branding
 
-The app follows Lovelace Brand R2 guidelines. For the full specification (color ramps, accessibility, visual effects), read `branding/BRANDING.md`.
+The `lovelace-branding` skill (`skills/lovelace-branding/`) is the single source of truth for all brand specifics -- colors, typography, patterns, assets, and usage guidelines. Read the skill before making branding decisions. Start with `SKILL.md` for the file index.
 
-## Quick Reference
+## Theme
 
-- **Theme**: Single dark theme. No light mode, no theme switching.
-- **Core colors**: Jet Black `#0A0A0A`, Pure White `#FFFFFF`, Cyber Green `#3FEA00`, Sonic Silver `#757575`
-- **Secondary colors**: Electric Blue `#003BFF`, Blaze Orange `#FF5C00`
-- **Semantic**: Amber `#FF9F0A` (warnings), Red `#EF4444` (errors)
-- **Fonts**: FK Grotesk (body), FK Grotesk Mono (headlines, buttons, code). Falls back to Inter / system-ui. See `public/fonts/README.md` for setup.
-- **Icons**: Material Design Icons (mdi) via Vuetify
+Single dark theme. No light mode, no theme switching.
 
-## Branding Files
+## Implementation Files
 
-These files are copied wholesale from the canonical branding source (`moongoose/ui/news-ui`). Update them by running `/update_branding`. Do **not** edit them in place.
+These files are project-owned. Consult the branding skill for the values and patterns they should implement.
 
-| File | Purpose |
-|---|---|
-| `branding/BRANDING.md` | Full brand specification |
-| `composables/useNewsTheme.ts` | Theme colors and CSS variable application |
-| `composables/useThemeClasses.ts` | Theme-aware class utilities |
-| `assets/theme-styles.css` | Theme CSS classes |
+| File | Role |
+|------|------|
+| `assets/brand-globals.css` | `:root` CSS variables and global typography/layout |
 | `assets/fonts.css` | `@font-face` declarations |
-| `assets/brand-globals.css` | Global CSS variables, typography, utilities |
-| `public/fonts/README.md` | Font setup instructions |
-| `public/LL-logo-full-wht.svg` | Primary logo (white, for dark backgrounds) |
+| `assets/theme-styles.css` | Theme-aware CSS utility classes |
+| `composables/useLovelaceTheme.ts` | Theme color palette and Vuetify theme activation |
+| `composables/useThemeClasses.ts` | Theme-aware class combination utilities |
 
-## Vuetify Theme
+## Integration
 
-The `lovelaceDark` Vuetify theme is defined in `nuxt.config.ts` under `vuetify.vuetifyOptions.theme`. This is the same theme used by the Broadchurch Portal. It provides Brand R2 colors to all Vuetify components automatically (primary = Cyber Green, secondary = Electric Blue, etc.). Component defaults (rounded buttons, outlined cards, etc.) are also set in `nuxt.config.ts` under `vuetify.vuetifyOptions.defaults`.
+- Use `useLovelaceTheme()` or `useThemeClasses()` in components for theme colors and class utilities.
+- The `lovelaceDark` Vuetify theme is defined in `nuxt.config.ts` under `vuetify.vuetifyOptions.theme`. It provides brand colors to all Vuetify components automatically. Component defaults are set under `vuetify.vuetifyOptions.defaults`.
+- CSS variables (`--lv-*`) and theme classes (`.theme-*`) are available globally via the stylesheets listed above.
+- `useLovelaceTheme` calls `theme.change('lovelaceDark')` to activate the Vuetify theme. This must match the theme name in `nuxt.config.ts`.
 
-## Integration
+## Updating
 
-- `composables/useCustomTheme.ts` is a thin adapter around `useNewsTheme`. Use `useCustomTheme()` or `useThemeClasses()` in components.
-- CSS variables (`--lv-green`, `--lv-black`, etc.) and theme classes (`.theme-card`, `.theme-text-primary`, etc.) are available globally.
-- `useNewsTheme` calls `theme.change('lovelaceDark')` to activate the Vuetify theme. This must match the theme name in `nuxt.config.ts`.
-- If you need to change how the branding integrates with Aether, modify the adapter -- not the branding files.
+Run `/update_branding` to sync these files with the latest branding skill guidelines. The command reads the skill, compares each implementation file against the guidelines, and updates as needed.

package/rules/design.mdc

@@ -20,7 +20,8 @@ When building from a project brief or user request, feel free to:
 
 - **Replace** `pages/index.vue` with the app's real home page
 - **Remove** any pages that don't fit the app
-- **Restructure** the navigation, layout, and branding entirely
+- **Restructure** the navigation and layout entirely
+- **Check** the branding is up to date with the `lovelace-branding` skill, and update as needed
 - **Keep** the infrastructure: `composables/`, `server/api/kv/`, `agents/`
 
 Do NOT treat the existing UI as something to preserve. Build what the

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

@@ -0,0 +1,184 @@
+# Data Dictionary — BNY Arbitrage Rebate Analysis
+
+## Source Description
+
+Interim Arbitrage Rebate Analysis reports prepared by BLX Group LLC for
+municipal bond issuers. Each report computes the arbitrage rebate liability
+under IRC Section 148 for a bond issue across a computation period. Reports
+include transmittal letters, legal opinions, notes/assumptions, summary
+schedules (rebate analysis, sources/uses of funds), and detailed per-fund
+cash flow and investment data.
+
+BNY (Bank of New York Mellon) serves as trustee. Orrick, Herrington &
+Sutcliffe LLP provides the accompanying legal opinion.
+
+## Entity Types
+
+### bond
+
+The municipal bond issue itself. One entity per unique bond across all reports.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `client_matter_number` | string | **Strong ID.** BLX Group client matter number (e.g. `42182-2748`). Invariant across all reports for the same bond. |
+| `bonds_name` | string | Full name of the bonds (e.g. "Multifamily Housing Revenue Refunding Bonds (Presidential Plaza at Newport Project-FHA Insured Mortgages) 1991 Series 1") |
+| `par_amount` | string | Total par amount of the bond issue (e.g. "$142,235,000") |
+| `dated_date` | string | Dated date of the bonds (e.g. "September 15, 1991") |
+| `issue_date` | string | Issue date of the bonds (e.g. "October 17, 1991") |
+| `bond_yield` | string | Arbitrage yield / allowable yield on investments (e.g. "7.420898%") |
+| `computation_period` | string | The computation period for this report (e.g. "October 17, 1991 through October 16, 2024") |
+| `rebate_computation_date` | string | End date of the computation period (e.g. "October 16, 2024") |
+| `cumulative_rebate_liability` | string | Total cumulative rebate liability (e.g. "$0.00") |
+| `rebate_payment_due` | string | Amount due to the US (e.g. "$0.00") |
+| `return_on_investments` | string | Weighted return on investments since prior computation date (e.g. "6.447251%") |
+| `shortfall_pct` | string | Shortfall percentage: return minus yield (e.g. "-0.973647%") |
+| `actual_gross_earnings` | string | Total actual gross earnings across all funds |
+| `allowable_gross_earnings` | string | Total allowable gross earnings at bond yield |
+| `excess_earnings` | string | Total excess (negative = under yield) |
+| `report_date` | string | Date the report was issued (e.g. "December 6, 2024") |
+
+### organization
+
+Companies, agencies, law firms, and financial institutions named in the reports.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `org_type` | string | Type: `government_agency`, `law_firm`, `financial_services`, `financial_institution`, `trust_company` |
+| `description` | string | Role in the deal (e.g. "Issuer", "Trustee", "Bond Counsel") |
+
+Expected entities:
+- New Jersey Housing and Mortgage Finance Agency (Issuer)
+- BLX Group LLC (Rebate Analyst)
+- Orrick, Herrington & Sutcliffe LLP (Bond Counsel)
+- BNY / Bank of New York Mellon (Trustee)
+- Willdan Financial Services (Prior Report preparer)
+- U.S. Department of the Treasury
+
+### fund_account
+
+Bond proceeds sub-accounts tracked for rebate computation purposes.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `fund_status` | string | Current status: `Active` or `Inactive` |
+| `computation_date_valuation` | string | Fair market value at computation date |
+| `gross_earnings` | string | Total gross earnings for the fund |
+| `internal_rate_of_return` | string | IRR on the fund's investments |
+| `excess_earnings` | string | Excess earnings (negative = below yield) |
+
+Expected entities:
+- Reserve I Account
+- Reserve II Account
+- Prior Rebate Liability
+- Liquidity I Account
+- Liquidity II Account
+
+Additional fund accounts mentioned in Notes and Assumptions:
+- Revenue Account (bona fide debt service fund, excluded from rebate)
+- Escrow Fund
+- Debt Service Reserve Account
+- Construction Account
+
+### financial_instrument
+
+Securities held within fund accounts (investments of bond proceeds).
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `par_amount` | string | Par amount of the security |
+| `coupon` | string | Coupon rate (e.g. "7.000%" or "Variable") |
+| `maturity_date` | string | Maturity date |
+| `settlement_date` | string | Settlement date |
+| `settlement_price` | string | Settlement price (e.g. "100.000") |
+| `yield` | string | Yield on the security |
+| `accreted_price` | string | Accreted price |
+| `accrued_interest` | string | Accrued interest amount |
+| `value` | string | Total value (par + accrued interest) |
+
+Expected entities (scoped per fund via `entity_context_from_title`):
+- Morgan IA (7% coupon, institutional investment)
+- Federated MM (variable rate money market fund)
+
+### legal_agreement
+
+Governing legal documents referenced in the reports.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `agreement_type` | string | Type: `arbitrage_certificate`, `trust_indenture`, `engagement_letter` |
+| `description` | string | Description of the agreement's role |
+
+Expected entities:
+- Certificate as to Arbitrage (Section 8, Section 21 referenced)
+- Prior Report (Willdan Financial Services, December 17, 2008)
+
+### location
+
+Addresses and jurisdictions.
+
+Expected entities:
+- Trenton, NJ (Issuer address)
+- Dallas, TX (BLX Group address)
+- New York, NY (Orrick address)
+- State of New Jersey
+
+### person
+
+Signatories, if extractable from signatures on transmittal letters and opinions.
+May be sparse — many PDFs have illegible or absent signature blocks.
+
+## Relationships
+
+| Relationship | Domain | Target | Description |
+|-------------|--------|--------|-------------|
+| `issuer_of` | organization | bond | Issuer issued the bonds |
+| `trustee_of` | organization | bond | Trustee of the bond issue |
+| `advisor_to` | organization | bond | BLX Group as rebate analyst; Orrick as bond counsel |
+| `fund_of` | fund_account | bond | Fund account belongs to the bond issue |
+| `holds_investment` | fund_account | financial_instrument | Fund holds a security as an investment |
+| `party_to` | organization | legal_agreement | Entity is party to an agreement |
+| `located_at` | organization | location | Organization's address |
+| `predecessor_of` | legal_agreement | legal_agreement | Prior Report preceded current Report |
+
+## Events
+
+| Event | Severity | Description |
+|-------|----------|-------------|
+| Rebate computation | medium | Periodic computation of arbitrage rebate liability |
+| Bond issuance | high | Original issuance of the bonds (October 17, 1991) |
+| Bond refunding | high | Refunding of prior 1985 Series F and G bonds |
+| Fund valuation | medium | Valuation of fund accounts at computation date |
+| Rebate payment determination | high | Determination that rebate payment is/isn't due |
+| Report issuance | low | Issuance of this rebate analysis report |
+
+## Table Extraction
+
+### Schedule A — Summary of Rebate Analysis
+
+Maps to `rebate_analysis` table config. Key column: Fund Description.
+Each row becomes a `fund_account` entity with properties for status,
+valuation, earnings, IRR, and excess earnings.
+
+### Schedule B — Sources & Uses of Funds
+
+Maps to `sources_of_funds` and `uses_of_funds` table configs. Uses
+`document_entity_from_title` mode to attach line items as properties
+on the bond entity.
+
+### Security Holdings (Schedules C1, D1, F1, G1)
+
+Maps to `security_tables` config. Key column: Security Type. Each
+security becomes a `financial_instrument` entity scoped by fund
+account title. Properties: par amount, coupon, maturity, yield, etc.
+
+### Cash Flow Tables (Schedules C2, D2, E1, F2, G2)
+
+New table config needed. These are the largest tables — hundreds of rows
+of deposit/withdrawal transactions for each fund account. Columns:
+Date, Description, Cash Flow, Muni-Days/Computation Date, FV Factor
+at bond yield, FV As Of at bond yield, FV Factor at IRR, FV As Of at IRR.
+
+## Citations
+
+All extracted data should cite the specific schedule and page number
+within the source PDF. The PDF filename serves as the document identifier.