spec: add frontier-efficient specification (#3345)

## New Specification: `frontier-efficient`

Related to #3342

---

### specification.md

# frontier-efficient: Efficient Frontier for Portfolio Optimization

## Description

The efficient frontier is a fundamental visualization in Modern
Portfolio Theory (MPT) that displays a curve of optimal portfolios
offering the highest expected return for each level of risk (standard
deviation). Portfolios on the frontier are "efficient" because no other
portfolio exists with higher return for the same risk, or lower risk for
the same return. This plot is essential for asset allocation decisions
and understanding the risk-return tradeoff in investment portfolios.

## Applications

- Portfolio managers selecting optimal asset allocations based on client
risk tolerance
- Financial advisors demonstrating the benefits of diversification to
investors
- Quantitative analysts comparing actual portfolio positions against
theoretical optimums
- Academic research in finance and economics illustrating mean-variance
optimization concepts

## Data

- `return` (numeric) - Expected portfolio return (annualized, typically
0.0-0.3)
- `risk` (numeric) - Portfolio risk as standard deviation (annualized,
typically 0.0-0.4)
- `weight` (optional, list) - Asset weights for each portfolio point
- Size: 50-500 simulated portfolios plus the efficient frontier curve
- Example: Randomly generated portfolios from 5-10 asset universe with
historical return/covariance data

## Notes

- X-axis should show risk (standard deviation), Y-axis should show
expected return
- The efficient frontier curve should be clearly distinguished (thicker
line, distinct color)
- Include random portfolio scatter points to show suboptimal portfolios
below the frontier
- Mark key points: minimum variance portfolio, maximum Sharpe ratio
(tangency) portfolio
- Optional: Show capital market line from risk-free rate tangent to
frontier
- Color coding can indicate Sharpe ratio for scatter points

---

**Next:** Add `approved` label to the issue to merge this PR.

---
:robot: *[spec-create
workflow](https://github.com/MarkusNeusinger/pyplots/actions/runs/20832697032)*

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

plots/frontier-efficient/specification.md

@@ -0,0 +1,29 @@
+# frontier-efficient: Efficient Frontier for Portfolio Optimization
+
+## Description
+
+The efficient frontier is a fundamental visualization in Modern Portfolio Theory (MPT) that displays a curve of optimal portfolios offering the highest expected return for each level of risk (standard deviation). Portfolios on the frontier are "efficient" because no other portfolio exists with higher return for the same risk, or lower risk for the same return. This plot is essential for asset allocation decisions and understanding the risk-return tradeoff in investment portfolios.
+
+## Applications
+
+- Portfolio managers selecting optimal asset allocations based on client risk tolerance
+- Financial advisors demonstrating the benefits of diversification to investors
+- Quantitative analysts comparing actual portfolio positions against theoretical optimums
+- Academic research in finance and economics illustrating mean-variance optimization concepts
+
+## Data
+
+- `return` (numeric) - Expected portfolio return (annualized, typically 0.0-0.3)
+- `risk` (numeric) - Portfolio risk as standard deviation (annualized, typically 0.0-0.4)
+- `weight` (optional, list) - Asset weights for each portfolio point
+- Size: 50-500 simulated portfolios plus the efficient frontier curve
+- Example: Randomly generated portfolios from 5-10 asset universe with historical return/covariance data
+
+## Notes
+
+- X-axis should show risk (standard deviation), Y-axis should show expected return
+- The efficient frontier curve should be clearly distinguished (thicker line, distinct color)
+- Include random portfolio scatter points to show suboptimal portfolios below the frontier
+- Mark key points: minimum variance portfolio, maximum Sharpe ratio (tangency) portfolio
+- Optional: Show capital market line from risk-free rate tangent to frontier
+- Color coding can indicate Sharpe ratio for scatter points

plots/frontier-efficient/specification.yaml

@@ -0,0 +1,29 @@
+# Specification-level metadata for frontier-efficient
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: frontier-efficient
+title: Efficient Frontier for Portfolio Optimization
+
+# Specification tracking
+created: 2026-01-08T21:41:43Z
+updated: null
+issue: 3342
+suggested: MarkusNeusinger
+
+# Classification tags (applies to all library implementations)
+# See docs/reference/tagging-system.md for detailed guidelines
+tags:
+  plot_type:
+    - scatter
+    - line
+  data_type:
+    - numeric
+    - continuous
+  domain:
+    - finance
+    - statistics
+  features:
+    - basic
+    - 2d
+    - correlation
+    - color-mapped