better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/finance/finance-merger-model.md

@@ -0,0 +1,162 @@
+---
+title: "Merger Model — Build M&A accretion/dilution workbooks in Excel"
+sidebar_label: "Merger Model"
+description: "Build M&A accretion/dilution workbooks in Excel"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Merger Model
+
+Build M&A accretion/dilution workbooks in Excel.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/finance/merger-model` |
+| Path | `optional-skills/finance\merger-model` |
+| Version | `1.0.0` |
+| Author | Anthropic (adapted by Nous Research) |
+| License | Apache-2.0 |
+| Platforms | linux, macos, windows |
+| Tags | `finance`, `m-and-a`, `merger`, `accretion-dilution`, `excel`, `openpyxl`, `modeling`, `investment-banking` |
+| Related skills | [`excel-author`](/docs/user-guide/skills/optional/finance/finance-excel-author), [`pptx-author`](/docs/user-guide/skills/optional/finance/finance-pptx-author), [`dcf-model`](/docs/user-guide/skills/optional/finance/finance-dcf-model), [`3-statement-model`](/docs/user-guide/skills/optional/finance/finance-3-statement-model) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+## Environment
+
+This skill assumes **headless openpyxl** — you are producing an .xlsx file on disk.
+Follow the `excel-author` skill's conventions for cell coloring, formulas, named ranges, and sensitivity tables.
+Recalculate before delivery: `python /path/to/excel-author/scripts/recalc.py ./out/model.xlsx`.
+
+# Merger Model
+
+Build accretion/dilution analysis for M&A transactions. Models pro forma EPS impact, synergy sensitivities, and purchase price allocation. Use when evaluating a potential acquisition, preparing merger consequences analysis for a pitch, or advising on deal terms.
+
+## Workflow
+
+### Step 1: Gather Inputs
+
+**Acquirer:**
+- Company name, current share price, shares outstanding
+- LTM and NTM EPS (GAAP and adjusted)
+- P/E multiple
+- Pre-tax cost of debt, tax rate
+- Cash on balance sheet, existing debt
+
+**Target:**
+- Company name, current share price, shares outstanding (if public)
+- LTM and NTM EPS or net income
+- Enterprise value or equity value
+
+**Deal Terms:**
+- Offer price per share (or premium to current)
+- Consideration mix: % cash vs. % stock
+- New debt raised to fund cash portion
+- Expected synergies (revenue and cost) and phase-in timeline
+- Transaction fees and financing costs
+- Expected close date
+
+### Step 2: Purchase Price Analysis
+
+| Item | Value |
+|------|-------|
+| Offer price per share | |
+| Premium to current | |
+| Equity value | |
+| Plus: net debt assumed | |
+| Enterprise value | |
+| EV / EBITDA implied | |
+| P/E implied | |
+
+### Step 3: Sources & Uses
+
+| Sources | $ | Uses | $ |
+|---------|---|------|---|
+| New debt | | Equity purchase price | |
+| Cash on hand | | Refinance target debt | |
+| New equity issued | | Transaction fees | |
+| | | Financing fees | |
+| **Total** | | **Total** | |
+
+### Step 4: Pro Forma EPS (Accretion / Dilution)
+
+Calculate year-by-year (Year 1-3):
+
+| | Standalone | Pro Forma | Accretion/(Dilution) |
+|---|-----------|-----------|---------------------|
+| Acquirer net income | | | |
+| Target net income | | | |
+| Synergies (after tax) | | | |
+| Foregone interest on cash (after tax) | | | |
+| New debt interest (after tax) | | | |
+| Intangible amortization (after tax) | | | |
+| Pro forma net income | | | |
+| Pro forma shares | | | |
+| **Pro forma EPS** | | | |
+| **Accretion / (Dilution) %** | | | |
+
+### Step 5: Sensitivity Analysis
+
+**Accretion/Dilution vs. Synergies and Offer Premium:**
+
+| | $0M syn | $25M syn | $50M syn | $75M syn | $100M syn |
+|---|---------|----------|----------|----------|-----------|
+| 15% premium | | | | | |
+| 20% premium | | | | | |
+| 25% premium | | | | | |
+| 30% premium | | | | | |
+
+**Accretion/Dilution vs. Cash/Stock Mix:**
+
+| | 100% cash | 75/25 | 50/50 | 25/75 | 100% stock |
+|---|-----------|-------|-------|-------|------------|
+| Year 1 | | | | | |
+| Year 2 | | | | | |
+
+### Step 6: Breakeven Synergies
+
+Calculate the minimum synergies needed for the deal to be EPS-neutral in Year 1.
+
+### Step 7: Output
+
+- Excel workbook with:
+  - Assumptions tab
+  - Sources & uses
+  - Pro forma income statement
+  - Accretion/dilution summary
+  - Sensitivity tables
+  - Breakeven analysis
+- One-page merger consequences summary for pitch book
+
+## Important Notes
+
+- Always show both GAAP and adjusted (cash) EPS where relevant
+- Stock deals: use acquirer's current price for exchange ratio, note dilution from new shares
+- Include purchase price allocation — goodwill and intangible amortization matter for GAAP EPS
+- Synergy phase-in is critical — Year 1 is often only 25-50% of run-rate synergies
+- Don't forget foregone interest income on cash used and new interest expense on debt raised
+- Tax rate on synergies and interest adjustments should match the acquirer's marginal rate
+
+
+## Data sources — MCP first, web fallback
+
+Many passages below say "use the S&P Kensho MCP / Daloopa MCP / FactSet MCP". Those are commercial financial-data MCPs from the original Cowork plugin context. In Hermes:
+
+- **If you have any structured financial-data MCP configured** (Hermes supports MCP — see `native-mcp` skill), prefer it for point-in-time comps, precedent transactions, and filings.
+- **Otherwise**, fall back to:
+  - `web_search` / `web_extract` against SEC EDGAR (`https://www.sec.gov/cgi-bin/browse-edgar`) for US filings
+  - Company IR pages for press releases, earnings decks
+  - `browser_navigate` for interactive data portals
+  - User-provided data (explicitly ask when the context doesn't have it)
+- **Never fabricate**. If a multiple, precedent, or filing number can't be sourced, flag the cell as `[UNSOURCED]` and surface it to the user.
+
+## Attribution
+
+This skill is adapted from Anthropic's Claude for Financial Services plugin suite (Apache-2.0). The Office-JS / Cowork live-Excel paths have been removed; this version targets headless openpyxl via the `excel-author` skill's conventions. Original: https://github.com/anthropics/financial-services

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/finance/finance-polymarket.md

@@ -0,0 +1,97 @@
+---
+title: "Polymarket — Query Polymarket: markets, prices, orderbooks, history"
+sidebar_label: "Polymarket"
+description: "Query Polymarket: markets, prices, orderbooks, history"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Polymarket
+
+Query Polymarket: markets, prices, orderbooks, history.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/finance/polymarket` |
+| Path | `optional-skills/finance\polymarket` |
+| Version | `1.0.0` |
+| Author | Hermes Agent + Teknium |
+| License | MIT |
+| Platforms | linux, macos, windows |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Polymarket — Prediction Market Data
+
+Query prediction market data from Polymarket using their public REST APIs.
+All endpoints are read-only and require zero authentication.
+
+See `references/api-endpoints.md` for the full endpoint reference with curl examples.
+
+## When to Use
+
+- User asks about prediction markets, betting odds, or event probabilities
+- User wants to know "what are the odds of X happening?"
+- User asks about Polymarket specifically
+- User wants market prices, orderbook data, or price history
+- User asks to monitor or track prediction market movements
+
+## Key Concepts
+
+- **Events** contain one or more **Markets** (1:many relationship)
+- **Markets** are binary outcomes with Yes/No prices between 0.00 and 1.00
+- Prices ARE probabilities: price 0.65 means the market thinks 65% likely
+- `outcomePrices` field: JSON-encoded array like `["0.80", "0.20"]`
+- `clobTokenIds` field: JSON-encoded array of two token IDs [Yes, No] for price/book queries
+- `conditionId` field: hex string used for price history queries
+- Volume is in USDC (US dollars)
+
+## Three Public APIs
+
+1. **Gamma API** at `gamma-api.polymarket.com` — Discovery, search, browsing
+2. **CLOB API** at `clob.polymarket.com` — Real-time prices, orderbooks, history
+3. **Data API** at `data-api.polymarket.com` — Trades, open interest
+
+## Typical Workflow
+
+When a user asks about prediction market odds:
+
+1. **Search** using the Gamma API public-search endpoint with their query
+2. **Parse** the response — extract events and their nested markets
+3. **Present** market question, current prices as percentages, and volume
+4. **Deep dive** if asked — use clobTokenIds for orderbook, conditionId for history
+
+## Presenting Results
+
+Format prices as percentages for readability:
+- outcomePrices `["0.652", "0.348"]` becomes "Yes: 65.2%, No: 34.8%"
+- Always show the market question and probability
+- Include volume when available
+
+Example: `"Will X happen?" — 65.2% Yes ($1.2M volume)`
+
+## Parsing Double-Encoded Fields
+
+The Gamma API returns `outcomePrices`, `outcomes`, and `clobTokenIds` as JSON strings
+inside JSON responses (double-encoded). When processing with Python, parse them with
+`json.loads(market['outcomePrices'])` to get the actual array.
+
+## Rate Limits
+
+Generous — unlikely to hit for normal usage:
+- Gamma: 4,000 requests per 10 seconds (general)
+- CLOB: 9,000 requests per 10 seconds (general)
+- Data: 1,000 requests per 10 seconds (general)
+
+## Limitations
+
+- This skill is read-only — it does not support placing trades
+- Trading requires wallet-based crypto authentication (EIP-712 signatures)
+- Some new markets may have empty price history
+- Geographic restrictions apply to trading but read-only data is globally accessible

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/finance/finance-pptx-author.md

@@ -0,0 +1,191 @@
+---
+title: "Pptx Author — Build PowerPoint decks headless with python-pptx"
+sidebar_label: "Pptx Author"
+description: "Build PowerPoint decks headless with python-pptx"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Pptx Author
+
+Build PowerPoint decks headless with python-pptx.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/finance/pptx-author` |
+| Path | `optional-skills/finance\pptx-author` |
+| Version | `1.0.0` |
+| Author | Anthropic (adapted by Nous Research) |
+| License | Apache-2.0 |
+| Platforms | linux, macos, windows |
+| Tags | `powerpoint`, `pptx`, `python-pptx`, `presentation`, `finance` |
+| Related skills | [`excel-author`](/docs/user-guide/skills/optional/finance/finance-excel-author), [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# pptx-author
+
+Produce a .pptx file on disk using `python-pptx`. Use when you need to deliver a deck as a file artifact, not drive a live PowerPoint session.
+
+Adapted from Anthropic's `pptx-author` and `pitch-deck` skills in [anthropics/financial-services](https://github.com/anthropics/financial-services). The MCP / Office-JS branches of the originals are dropped — this assumes headless Python.
+
+For the broader, already-shipped PowerPoint authoring skill (slides, speaker notes, embeds, media), see the built-in `powerpoint` skill. This skill is a lighter-weight pattern tuned for model-backed decks (pitch decks, IC memos, earnings notes) where every number must trace to a source workbook.
+
+## Output contract
+
+- Write to `./out/<name>.pptx`. Create `./out/` if it does not exist.
+- Return the relative path in your final message.
+
+## Setup
+
+```bash
+pip install "python-pptx>=0.6"
+```
+
+## Core conventions
+
+### One idea per slide
+Title states the takeaway; body supports it. A slide titled "Q3 Revenue" is weak; "Revenue growth accelerated to 14% Y/Y in Q3" is strong.
+
+### Every number traces to the model
+If a figure on a slide came from `./out/model.xlsx`, footnote the sheet and cell.
+
+```
+Revenue: $1,250M  (Source: model.xlsx, Inputs!C3)
+```
+
+Never transcribe numbers from memory or from a summary — open the workbook, read the named range, and bind the deck value to it programmatically when you can.
+
+### Use the firm template when one is mounted
+If `./templates/firm-template.pptx` exists, load it so the deck inherits branded colors, fonts, and master layouts.
+
+```python
+from pptx import Presentation
+from pathlib import Path
+
+template = Path("./templates/firm-template.pptx")
+prs = Presentation(str(template)) if template.exists() else Presentation()
+```
+
+### Charts: PNG-from-model beats native pptx charts
+When fidelity matters (the model's chart styling must match the deck exactly), render the chart to PNG from the source workbook and embed the image. Native `pptx.chart` charts are fragile and often don't match firm conventions.
+
+```python
+from pptx.util import Inches
+slide.shapes.add_picture("./out/charts/football_field.png",
+                         Inches(1), Inches(2),
+                         width=Inches(8))
+```
+
+### No external sends
+This skill writes a file. It never emails, uploads, or posts. Orchestration layers handle delivery.
+
+## Skeleton
+
+```python
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.dml.color import RGBColor
+from pathlib import Path
+
+template = Path("./templates/firm-template.pptx")
+prs = Presentation(str(template)) if template.exists() else Presentation()
+
+# Title slide
+slide = prs.slides.add_slide(prs.slide_layouts[0])
+slide.shapes.title.text = "Project Aurora — Strategic Alternatives"
+slide.placeholders[1].text = "Preliminary Discussion Materials"
+
+# Valuation summary slide (title-only layout)
+slide = prs.slides.add_slide(prs.slide_layouts[5])
+slide.shapes.title.text = "Valuation implies $38–$52 per share across methodologies"
+
+# Add a table bound to model outputs
+rows, cols = 5, 4
+tbl_shape = slide.shapes.add_table(rows, cols,
+                                   Inches(0.5), Inches(1.5),
+                                   Inches(9), Inches(3))
+tbl = tbl_shape.table
+headers = ["Methodology", "Low ($)", "Mid ($)", "High ($)"]
+for c, h in enumerate(headers):
+    tbl.cell(0, c).text = h
+
+# In a real deck, read these from the model workbook with openpyxl
+data = [
+    ("Trading comps",     "35", "41", "48"),
+    ("Precedent M&A",     "39", "45", "52"),
+    ("DCF (base)",        "36", "43", "51"),
+    ("LBO (10% IRR)",     "33", "38", "44"),
+]
+for r, row in enumerate(data, start=1):
+    for c, val in enumerate(row):
+        tbl.cell(r, c).text = val
+
+# Embed a chart rendered from the model
+slide = prs.slides.add_slide(prs.slide_layouts[5])
+slide.shapes.title.text = "Football field — current price $42"
+slide.shapes.add_picture("./out/charts/football_field.png",
+                         Inches(1), Inches(1.8), width=Inches(8))
+
+Path("./out").mkdir(exist_ok=True)
+prs.save("./out/pitch-aurora.pptx")
+```
+
+## Binding deck numbers to the source workbook
+
+Read named ranges or specific cells from your Excel model so deck numbers never drift.
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook("./out/model.xlsx", data_only=True)
+def nr(name):
+    """Resolve a named range to its current computed value."""
+    rng = wb.defined_names[name]
+    sheet, coord = next(rng.destinations)
+    return wb[sheet][coord].value
+
+revenue_fy24 = nr("RevenueFY24")
+implied_mid  = nr("ImpliedSharePriceBase")
+```
+
+Then build deck content using those values:
+```python
+slide.shapes.title.text = f"Implied share price of ${implied_mid:.2f} (base case)"
+```
+
+Remember to recalculate the workbook before reading it — openpyxl only sees computed values if something has already calculated the sheet. Run the recalc helper in the `excel-author` skill first, or open/save through a real Excel session.
+
+## Slide-type checklist for pitch decks
+
+A typical banking pitch deck follows this structure. Not prescriptive, but useful as a starting skeleton:
+
+1. Cover / title
+2. Disclaimer
+3. Table of contents
+4. Situation overview
+5. Company snapshot (the target)
+6. Market / sector context
+7. Valuation summary (football field) — the money slide
+8. Trading comps detail
+9. Precedent transactions detail
+10. DCF summary
+11. Illustrative LBO / sponsor case
+12. Process considerations
+13. Appendix
+
+## When NOT to use this skill
+
+- Users in a live PowerPoint session with an Office MCP available — drive their live doc instead.
+- Non-financial slideware (quarterly all-hands, marketing decks) — use the broader `powerpoint` skill.
+- Decks with heavy animation, transitions, or speaker notes — use the broader `powerpoint` skill.
+
+## Attribution
+
+Conventions adapted from Anthropic's Claude for Financial Services plugin suite, Apache-2.0 licensed. Original: https://github.com/anthropics/financial-services/tree/main/plugins/agent-plugins/pitch-agent/skills/pptx-author

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/finance/finance-stocks.md

@@ -0,0 +1,112 @@
+---
+title: "Stocks — Stock quotes, history, search, compare, crypto via Yahoo"
+sidebar_label: "Stocks"
+description: "Stock quotes, history, search, compare, crypto via Yahoo"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Stocks
+
+Stock quotes, history, search, compare, crypto via Yahoo.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/finance/stocks` |
+| Path | `optional-skills/finance\stocks` |
+| Version | `0.1.0` |
+| Author | Mibay (Mibayy), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Stocks`, `Finance`, `Market`, `Crypto`, `Investing` |
+| Related skills | [`dcf-model`](/docs/user-guide/skills/optional/finance/finance-dcf-model), [`comps-analysis`](/docs/user-guide/skills/optional/finance/finance-comps-analysis), [`lbo-model`](/docs/user-guide/skills/optional/finance/finance-lbo-model) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Stocks Skill
+
+Read-only market data via Yahoo Finance. Five commands: `quote`, `search`,
+`history`, `compare`, `crypto`. Python stdlib only — no API key, no pip
+installs. Yahoo's endpoint is unofficial and may rate-limit or change.
+
+## When to Use
+
+- User asks for a current stock price (AAPL, TSLA, MSFT, ...)
+- User wants to look up a ticker by company name
+- User wants OHLCV history or performance over a date range
+- User wants to compare several tickers side by side
+- User asks for a crypto price (BTC, ETH, SOL, ...)
+
+## Prerequisites
+
+Python 3.8+ stdlib only. Optional: set `ALPHA_VANTAGE_KEY` to enrich
+`market_cap`, `pe_ratio`, and 52-week levels when Yahoo's crumb-protected
+fields come back null. Free key: https://www.alphavantage.co/support/#api-key
+
+## How to Run
+
+Invoke through the `terminal` tool. Once installed:
+
+```
+SCRIPT=~/.hermes/skills/finance/stocks/scripts/stocks_client.py
+python $SCRIPT quote AAPL
+```
+
+All output is JSON on stdout — pipe through `jq` if you want to slice it.
+
+## Quick Reference
+
+```
+python $SCRIPT quote AAPL
+python $SCRIPT quote AAPL MSFT GOOGL TSLA
+python $SCRIPT search "Tesla"
+python $SCRIPT history NVDA --range 6mo
+python $SCRIPT compare AAPL MSFT GOOGL
+python $SCRIPT crypto BTC ETH SOL
+```
+
+## Commands
+
+### `quote SYMBOL [SYMBOL2 ...]`
+
+Current price, change, change%, volume, 52-week high/low.
+
+### `search QUERY`
+
+Find tickers by company name. Returns top 5: symbol, name, exchange, type.
+
+### `history SYMBOL [--range RANGE]`
+
+Daily OHLCV plus stats (min, max, avg, total return %). Ranges: `1mo`,
+`3mo`, `6mo`, `1y`, `5y`. Default: `1mo`.
+
+### `compare SYMBOL1 SYMBOL2 [...]`
+
+Side-by-side: price, change%, 52-week performance.
+
+### `crypto SYMBOL [SYMBOL2 ...]`
+
+Crypto prices. Pass `BTC` (the script appends `-USD` automatically).
+
+## Pitfalls
+
+- Yahoo Finance's API is unofficial. Endpoints can change or rate-limit
+  without notice — if requests start failing, that's why.
+- `market_cap` and `pe_ratio` may return null on `quote` when Yahoo's
+  crumb session isn't established. Set `ALPHA_VANTAGE_KEY` to backfill.
+- Add a small delay between bulk requests to avoid rate-limiting.
+- This is read-only — no order placement, no account integration.
+
+## Verification
+
+```
+python ~/.hermes/skills/finance/stocks/scripts/stocks_client.py quote AAPL
+```
+
+Returns a JSON object with `symbol: "AAPL"` and a numeric `price` field.