# Forge MCP — freelance pipeline operations

**Version:** 1.0.0  
**Quality gate:** `.\make.ps1` (black, ruff, mypy, pytest cov≥90%, Martin limits)

Forge hunts **public, ToS-safe** job APIs, ranks listings by capability match and
money heat, pushes HOT cards (Telegram + local digest), and tracks the
pipeline from NEW → paid. Client pitches stay in the listing language;
operator briefs are in Russian.

## What is in scope / out of scope

| In scope | Out of scope |
|---|---|
| RemoteOK, Remotive, Himalayas, Arbeitnow(+UK), Jobicy, HN Who's Hiring | Upwork / Freelancer.com scraping |
| Manual `capture_lead` for off-board finds | Auto-apply without a human |
| Telegram buttons + rituals | Secret logging / token echo |

## Install

```powershell
pip install -e ".[dev]"
copy .env.example .env   # fill BOT_TOKEN + CHAT_ID
.\make.ps1               # must exit 0
```

CLIs: `forge-hunt`, `forge-telegram-bot`, `forge-morning`, `forge-evening`, `forge-mcp`.

## Configuration

Secrets and knobs live in `.env` (gitignored). See `.env.example`.

| Variable | Role |
|---|---|
| `BOT_TOKEN` / `CHAT_ID` | Telegram (aliases → `FORGE_TELEGRAM_*`) |
| `FORGE_CONTRACT_ONLY=1` | Strict contract/freelance HOT gate |
| `FORGE_ANCHOR_*` / `FORGE_WALK_AWAY` | One killer offer + floor |
| `FORGE_PROOF_URL` | Optional case link appended to SHORT |
| `FORGE_PAUSED_BOARDS` | Manual board deprioritization |
| `FORGE_DB` / `FORGE_DIGEST_PATH` | Storage / digest overrides |

## Operations (money loop)

1. `set_watchlist([...])` — narrow magnets  
2. `forge-hunt` every ~30m — HOT + Telegram buttons  
3. Copy PITCH → send → **Proposed** (target <15 min NEW→proposed)  
4. `forge-morning` / `forge-evening` — queue + follow-ups + board pause  
5. **Won** + `log_win_reason` → learning / A/B / packages  

Windows schedules: `scripts\schedule_hunt.ps1`, `schedule_rituals.ps1`, `schedule_bot.ps1`  
(scripts resolve project root from their own location).

## MCP

```json
{
  "mcpServers": {
    "forge": {
      "command": "python",
      "args": ["-m", "forge.presentation.mcp_server"]
    }
  }
}
```

Core tools: `hunt_jobs`, `act_now`, `morning_digest`, `evening_followup`,
`draft_proposal`, `brief_lead`, `rate_advice`, `check_red_flags`,
`follow_ups`, `sla_status`, `chase_leads`, `package_prices`,
`pause_weak_boards`, `platform_roi`, `board_advice`, `win_journal`,
`log_win_reason`, `pitch_ab_stats`, `set_watchlist`, `pipeline_status`,
`earnings_summary`, `capture_lead`, `scan_for_leads`, `hot_leads`.

## Architecture

```
src/forge/
  entities/         # Lead FSM, match, heat, gates, pricing, i18n
  use_cases/        # hunt, rituals, pipeline, learning, act-now
  interfaces/       # ports (repos, sources, notifier)
  infrastructure/   # SQLite, HTTP boards, Telegram, .env loader
  presentation/     # MCP + CLIs + composition root
```

Clean architecture: use cases depend on ports; composition wires adapters.
Persistence: SQLite (`~/.forge/forge.db` by default) with additive migrations.

## Quality / acceptance

See [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md). Summary:

- `.\make.ps1` exits 0  
- ≥90% line coverage on `forge` (CLIs/MCP omitted by design)  
- No secrets in repo; Telegram errors redacted  
- Martin limits: file ≤300 lines, fn ≤25 lines, ≤4 args, CC≤10, nesting≤3  

## License

MIT — see [LICENSE](LICENSE).