diff --git a/AGENTS.md b/AGENTS.md index 8bd0e39..b13c5aa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,3 +3,67 @@ This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices. + +# Central Behavioral Framework & Dev-Chain Workflow + +This document establishes the binding operational rules, technical constraints, defensive coding protocols, and repository documentation duties for the development of the high-performance Financial & Macroeconomic Quant Terminal. + +--- + +## 1. Role & Identity +You operate as an **Elite Quant Full-Stack Developer and Technical Writer**. The core mission is to construct and deploy robust, mathematically rigorous, and offline-resilient modules for the Financial & Macroeconomic Quant Terminal. + +--- + +## 2. Rigid Tech Stack Constraints +* **Frontend & Layout**: Next.js (App Router), Tailwind CSS v4, shadcn/ui, Recharts. +* **State Management**: Zustand client-side store, anchored in `lib/store.ts`. +* **Data Ingestion**: Live hybrid endpoints connecting to the Financial Modeling Prep (FMP) API for corporate data and the Federal Reserve (FRED) CSV repository for macroeconomic metrics. +* **Strict Prohibitions**: Do **NOT** install or use Prisma, Docker, NestJS, or Microsoft Fluent UI. Keep the workspace lightweight, fast, and offline-resilient via local state fallbacks. + +--- + +## 3. Blind Environment Rules (Defensive Coding) +* **No Live Visual Access**: You cannot see or interact directly with the running user interface. +* **Defensive Practice**: All network operations, API parsing, and state updates must be guarded by strict `try/catch` blocks. +* **Console Logging**: Implement native console logging for error tracking and runtime debugging. +* **Verification Instructions**: You must always provide the user with precise, step-by-step instructions to verify changes manually in their browser (e.g., *"Please open the [⚡ AI Special Silo] tab, verify that the sparkline renders the 8-quarter history, and click [📖 Modulerklärung] to confirm the equations modal display"*). + +--- + +## 4. Mandatory Repository Documentation Duties +Upon every significant code modification or new feature phase implementation, you must independently update: +1. **`DEV_LOG.md`**: A chronological record of all changes, packages installed (via npm), and active bugs or items. +2. **`QUANT_ROADMAP.md`**: The macro-architecture master blueprint tracking our 6-level data matrix and econometric models. +3. **`ARCHITECT_HANDOVER.md`**: The functional state of the terminal, active data proxy JSON models, and core mathematical thresholds. + +--- + +## 5. Global Operation Triggers + +### A. Session Initiation +* **Trigger**: `"Lass uns die Session starten"` +* **Action**: Execute automatic synchronization: + 1. Check repository status (`git status`). + 2. Pull remote changes (`git pull`). + 3. Check `package.json` for delta updates and run `npm install` if dependencies changed. + 4. Output a concise confirmation report. + +### B. Dev-Chain Protocol +* **Trigger**: `"/devchain #[ID]"` +* **Action**: Initiate the phase-locked development workflow: + 1. Read the relevant issue specification file `Issue-Dev-Chain.md` in the workspace. + 2. Create and checkout a dedicated git branch named `issue/[id]-[title]`. + 3. Prepend active status tags (e.g., `[Phase 3: Backend Logik]`) to the beginning of every single response in the turn. + 4. Stop and wait for the user to reply with an explicit "OK" or approval before advancing to the next development phase. + +### C. Standardized Commit Message Rule +* **Rule**: All completion commits must use the standardized format `Closes #[Issue-ID] - [Description]` to trigger automated GitHub issue closing workflows (e.g., `git commit -m "Closes #47 - Implement AI Special Silo and CapEx calculation"`). + +--- + +## 6. The Maximal Explanation Principle +* **Educational Overlay Requirement**: Every single dashboard module or tab component MUST feature a prominently displayed **`[📖 Modulerklärung]`** button. +* **Prose Depth**: Clicking this button must trigger a comprehensive, full-screen overlay handbook written in professional English. +* **No Shortcuts**: Do not use code shortcuts or inline placeholders. +* **LaTeX Math**: Detail every single econometric variable, data source, financial calculation, and portfolio allocation implication using beautiful, block-formatted LaTeX via `react-katex`. diff --git a/ARCHITECT_HANDOVER.md b/ARCHITECT_HANDOVER.md new file mode 100644 index 0000000..982fd0b --- /dev/null +++ b/ARCHITECT_HANDOVER.md @@ -0,0 +1,108 @@ +# Architect Handover Document (`ARCHITECT_HANDOVER.md`) + +This document outlines the functional state of the Quant Terminal, the mathematical thresholds used by the HSL status triggers, and the structures of active data proxies. + +--- + +## 1. Functional State of the Station + +The Quant Terminal operates with 7 primary functional modules mounted in [app/page.tsx](file:///c:/Users/jannr/.gemini/antigravity/scratch/investment-sandbox/app/page.tsx): +1. **Sandbox** (`activeTab === 'sandbox'`): Solves Swamy-Arora random effects regressions. +2. **Scanner** (`activeTab === 'scanner'`): Visualizes live asset scanners. +3. **Insider** (`activeTab === 'insider'`): Tracks corporate insider trades. +4. **Krypto Bayes** (`activeTab === 'crypto'`): Implements Bayesian on-chain learning models. +5. **Ökonometrie** (`activeTab === 'events'`): Conducts econometric event studies. +6. **Eco Indicators** (`activeTab === 'macro'`): Monitors 21 FRED macroeconomic and credit indicators. +7. **AI Special Silo** (`activeTab === 'tech'`): Tracks the tech CapEx overinvestment cycle. + +All endpoints support a 60-minute in-memory caching TTL. + +--- + +## 2. Core Mathematical Thresholds & Status Triggers + +Indicators in the cockpit cards use HSL-tailored status lights (Emerald-Green, Amber, Flashing Neon Rose-Red). + +### Macroeconomics Silo (Module 6) +* **Card 1 (Inflation & Consumer)**: + * `RED`: CPI Inflation YoY $\ge 3.0\%$, Credit Card Delinquencies $> 4.5\%$, or Personal Savings Rate $< 3.0\%$. + * `AMBER`: CPI Inflation $\ge 2.5\%$, Credit Card Delinquencies $> 3.5\%$, or Personal Savings Rate $< 4.0\%$. + * `GREEN`: Normal operations. +* **Card 2 (Valuation & Liquidity)**: + * `RED`: Buffett Indicator Ratio $> 150\%$, or M2 money supply trend is `DOWN`. + * `AMBER`: Buffett Indicator Ratio $> 130\%$, or Reverse Repo (RRP) volume $< 400$B$. + * `GREEN`: Normal valuation limits. +* **Card 3 (Yield Curve & Credit)**: + * `RED`: 2S10S yield spread is inverted ($< 0.0\%$), or High-Yield Credit Spread $> 5.0\%$. + * `AMBER`: 2S10S spread $< 0.1\%$, or High-Yield Credit Spread $> 4.0\%$. + * `GREEN`: Positive term structure. + +### AI & Tech Silo (Module 7) +* **Card 1 (Monetization Gap)**: + * `RED`: Minimum Monetization Gap among constituents $< -15\%$ (diminishing segment returns). + * `AMBER`: Minimum Monetization Gap $< 0\%$ (CapEx growth outstripping segment revenue growth). + * `GREEN`: Positive monetization gap (revenue growing faster than capital expenditures). +* **Card 2 (Supply-Chain Velocity)**: + * `RED`: Velocity Index $< 1.8x$, or velocity trend is `DOWN` (buyers reducing forward commitments). + * `AMBER`: Velocity Index $< 3.0x$ (buyer commitments softening relative to supplier inventory). + * `GREEN`: Normal supply speeds ($\ge 3.0x$). +* **Card 3 (Infrastructure Leverage)**: + * `RED`: Maximum CapEx-to-Depreciation Ratio $> 4.0x$, or maximum Debt-to-Equity Ratio $> 1.2$ (highly leveraged node expansion). + * `AMBER`: Maximum CapEx-to-Depreciation $> 2.5x$, or maximum Debt-to-Equity $> 0.8$. + * `GREEN`: Asset expansion supported by low-leverage ratios. + +--- + +## 3. Active Data Proxy Models + +### AI Special Silo API Response Schema (`/api/tech/ai`) +```json +{ + "dates": ["Q3-24", "Q4-24", "Q1-25", "Q2-25", "Q3-25", "Q4-25", "Q1-26", "Q2-26"], + "liveDataAvailable": false, + "timestamp": 1781274890000, + "metrics": { + "monetizationGap": { + "name": "ROI-to-CapEx & Monetization Gap", + "tickers": { + "NVDA": { + "current": -5.3, + "previous": -4.2, + "trend": "DOWN", + "segmentRevenueGrowth": 3.1, + "capexGrowth": 8.4, + "roiToCapex": 2.6, + "data": [ + { "quarter": "Q3-24", "monetizationGap": 0.0, "roiToCapex": 0.0, "segmentRevenueGrowth": 0.0, "capexGrowth": 0.0 } + ] + } + } + }, + "supplyChain": { + "name": "Nvidia Supply-Chain Velocity Index", + "unit": "x", + "currentVelocity": 2.2, + "previousVelocity": 2.5, + "currentTurnover": 5.7, + "currentObligations": 18700, + "trend": "DOWN", + "data": [ + { "quarter": "Q3-24", "nvdaInvTurnover": 5.2, "aggregateObligations": 14500, "velocityIndex": 3.2 } + ] + }, + "infrastructure": { + "name": "Tech Infrastructure Leverage & Cluster Expansion", + "tickers": { + "MSFT": { + "currentDE": 0.3, + "currentCapExDep": 3.9, + "trendDE": "UP", + "data": [ + { "quarter": "Q3-24", "de": 0.34, "capexDep": 3.2, "debt": 77800, "equity": 228900 } + ] + } + } + } + } +} +``` diff --git a/DEV_LOG.md b/DEV_LOG.md new file mode 100644 index 0000000..8512f61 --- /dev/null +++ b/DEV_LOG.md @@ -0,0 +1,32 @@ +# Chronological Development Log (`DEV_LOG.md`) + +This document tracks all modifications, npm packages, active compilation states, and testing notes chronologically. + +--- + +## [2026-06-12] - Phase 4.7 Deployment & Behavioral Rule Lock + +### Added +* **`QUANT_ROADMAP.md`**: Created the centralized quantitative architecture blueprint tracking our 6-level cockpit data matrix and individual asset scoring metrics. +* **`AGENTS.md`**: Rewrote the central behavioral framework containing nextjs agent rules, tech stack constraints, blind environment rules, and `/devchain` session protocols. +* **`DEV_LOG.md`**: Initialized this log to keep track of development history. +* **`ARCHITECT_HANDOVER.md`**: Initialized the architect handover documentation. +* **AI Special Silo Backend Route**: Deployed [/api/tech/ai/route.ts](file:///c:/Users/jannr/.gemini/antigravity/scratch/investment-sandbox/app/api/tech/ai/route.ts) with a 60-minute cache and calculations for the Monetization Gap, Nvidia SC Velocity Index, and Tech Infrastructure Leverage. +* **AI Special Silo UI Workstation**: Deployed [AiSpecialSilo.tsx](file:///c:/Users/jannr/.gemini/antigravity/scratch/investment-sandbox/components/modules/tech/AiSpecialSilo.tsx) featuring a glassmorphic analytics viewer, dynamic Recharts sparklines, and status indicators. +* **AI Special Silo English Handbook**: Deployed [TechMathModal.tsx](file:///c:/Users/jannr/.gemini/antigravity/scratch/investment-sandbox/components/modules/tech/TechMathModal.tsx) displaying extensive documentation and BlockMath LaTeX equations. + +### Modified +* **`app/page.tsx`**: Integrated the `[⚡ AI Special Silo]` tab inside the main workstation navigation headers. + +### Dependencies Verified +* `next` (v16.2.7) +* `react` (v19.2.4) +* `recharts` (v3.8.1) +* `react-katex` (v3.1.0) +* `katex` (v0.17.0) +* `lucide-react` (v1.17.0) +* `zustand` (v5.0.14) + +### Active Bugs / Compile Status +* **Active Bugs**: None. +* **Type Checker Status**: Verified clean compilation (`npx tsc --noEmit` returns exit code 0).