refactor: restructure to clean architecture

fix: restore ScoringConfig improvements lost in refactor commit

docs: rewrite README and CLAUDE.md to reflect current architecture

code-format

code fixes

tests/PortfolioAdvisor.test.js

@@ -0,0 +1,49 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { PortfolioAdvisor } from '../src/finance/PortfolioAdvisor.js';
+import { SIGNAL } from '../src/config/constants.js';
+
+const advisor = new PortfolioAdvisor();
+
+test('_position: computes gain/loss correctly', () => {
+  const pos = advisor._position({ costBasis: 100, shares: 10 }, 150);
+  assert.equal(pos.gainLossPct, '50.0');
+  assert.equal(pos.marketValue, '1500.00');
+  assert.equal(pos.totalCost, '1000.00');
+});
+
+test('_position: returns null gainLoss when price unavailable', () => {
+  const pos = advisor._position({ costBasis: 100, shares: 10 }, null);
+  assert.equal(pos.gainLossPct, null);
+  assert.equal(pos.marketValue, null);
+});
+
+test('_advice: Strong Buy → Hold & Add', () => {
+  const { action } = advisor._advice(SIGNAL.STRONG_BUY, { costBasis: 100, shares: 10 }, 150);
+  assert.equal(action, '🟢 Hold & Add');
+});
+
+test('_advice: Avoid + loss → Sell (Cut Loss)', () => {
+  const { action } = advisor._advice(SIGNAL.AVOID, { costBasis: 150, shares: 10 }, 100);
+  assert.equal(action, '🔴 Sell (Cut Loss)');
+});
+
+test('_advice: Avoid + profit → Sell (Take Profits)', () => {
+  const { action } = advisor._advice(SIGNAL.AVOID, { costBasis: 100, shares: 10 }, 150);
+  assert.equal(action, '🔴 Sell (Take Profits)');
+});
+
+test('_advice: Speculation + >20% gain → Reduce Position', () => {
+  const { action } = advisor._advice(SIGNAL.SPECULATION, { costBasis: 100, shares: 10 }, 125);
+  assert.equal(action, '🟠 Reduce Position');
+});
+
+test('_cryptoAdvice: no price → No price data', () => {
+  const { action } = advisor._cryptoAdvice({ costBasis: 100, shares: 1 }, null);
+  assert.equal(action, '⚪ No price data');
+});
+
+test('_cryptoAdvice: >100% gain → Consider taking profits', () => {
+  const { action } = advisor._cryptoAdvice({ costBasis: 10000, shares: 1 }, 25000);
+  assert.equal(action, '🟠 Consider taking profits');
+});