docs(i18n): add English translations for 8 missing documents

Translated files: - AI Swarm Collaboration (overview + detailed technical doc) - Lessons Learned the Hard Way - OpenCode CLI Configuration - Four Phases x Twelve Principles Methodology - Canvas Whiteboard-Driven Development - Polymarket Link Format Specification - Polymarket Arbitrage Complete Guide Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
2026-08-20 14:28:05 +00:00 · 2026-01-10 23:20:19 +08:00
parent 59821fffa1
commit fab5041494
8 changed files with 1467 additions and 0 deletions
@@ -0,0 +1,99 @@
+# Polymarket Link Format Specification
+
+## Problem Description
+
+Generated Polymarket links return "Oops...we didn't forecast this" error page, even when HTTP status code is 200.
+
+## Root Cause
+
+Polymarket API returns two different slugs:
+
+| Field | Name | Usage |
+|------|------|------|
+| `slug` | Market Slug | Market identifier, **cannot be used for URL** |
+| `events[0].slug` | Event Slug | Event identifier, **must be used for URL** |
+
+### Example Comparison
+
+```
+Market: "Lighter market cap (FDV) >$1B one day after launch?"
+
+API returns:
+  slug: "lighter-market-cap-fdv-1b-one-day-after-launch"        ❌ Wrong
+  events[0].slug: "lighter-market-cap-fdv-one-day-after-launch" ✅ Correct
+
+Wrong link: https://polymarket.com/event/lighter-market-cap-fdv-1b-one-day-after-launch
+Correct link: https://polymarket.com/event/lighter-market-cap-fdv-one-day-after-launch
+```
+
+Note the difference: market slug contains `-1b-`, event slug doesn't.
+
+## Why HTTP 200 But Page Errors?
+
+Polymarket frontend is an SPA (Single Page Application):
+- All `/event/*` paths return HTTP 200 (returns HTML shell)
+- Frontend JS loads and then requests data
+- If slug is invalid, frontend displays "Oops" error
+
+**Conclusion: HTTP status code cannot validate link validity.**
+
+## Correct Link Generation Method
+
+```javascript
+// ✅ Correct
+const getLink = (market) => {
+  const events = market.events || [];
+  const slug = events[0]?.slug || market.slug;  // Prioritize event slug
+  return `https://polymarket.com/event/${slug}`;
+};
+
+// ❌ Wrong
+const getLink = (market) => {
+  return `https://polymarket.com/event/${market.slug}`;
+};
+```
+
+## API Response Structure
+
+```json
+{
+  "question": "Lighter market cap (FDV) >$1B one day after launch?",
+  "slug": "lighter-market-cap-fdv-1b-one-day-after-launch",
+  "events": [
+    {
+      "slug": "lighter-market-cap-fdv-one-day-after-launch",
+      "title": "Lighter Market Cap (FDV) One Day After Launch"
+    }
+  ]
+}
+```
+
+## Validation Methods
+
+Can't just check HTTP status code, need to:
+
+```bash
+# Method 1: Check if page content contains error
+curl -s "https://polymarket.com/event/xxx" | grep -q "didn't forecast" && echo "Invalid"
+
+# Method 2: Compare slug returned by API
+curl -s "https://gamma-api.polymarket.com/markets?slug=xxx" | jq '.events[0].slug'
+```
+
+## Affected Files
+
+When fixing, check link generation logic in these files:
+
+- `scripts/csv-report-api.js`
+- `scripts/csv-report.js`
+- `signals/*/formatter.js` (if generating links)
+
+## Fix Record
+
+- **Date**: 2024-12-31
+- **Issue**: csv-report-api.js uses `m.slug` to generate links
+- **Fix**: Changed to `m.events[0]?.slug || m.slug`
+
+---
+
+**Rule: Any code generating Polymarket links must use `events[0].slug`, not `slug`.**
@@ -0,0 +1,91 @@
+# The Secret to Guaranteed Profits: Complete Polymarket Arbitrage Guide
+
+## You Trade Two Types of Assets: YES and NO Shares
+
+In Polymarket, what you trade mainly falls into two categories:
+
+1. If the event happens (YES)
+Each 1 share of YES you hold will be exchanged for $1 at settlement.
+
+2. If the event doesn't happen (NO)
+Each 1 share of NO you hold will be exchanged for $1 at settlement.
+
+Core rule: The side that guesses correctly, their shares become worth $1; the side that guesses wrong, their shares become worth zero.
+
+## The Theoretical Iron Law: The Perfect Balance of System Design
+
+YES share price + NO share price = $1
+
+This is the inherent mathematical balance of the system, and the cornerstone of all arbitrage logic.
+For example: If the YES share market price is $0.60, then the theoretical NO share price must be $0.40.
+
+## Theory is Perfect, But Reality is... Prices are Generated by Global User Trading
+
+In the real world, prices are not set by formulas, but determined by the collective behavior of global traders (emotions, information asymmetry, strategies). This leads to the theoretical balance being frequently broken.
+
+### YES share price + NO share price ≠ $1
+
+This imbalance is what we call "Price Dislocation".
+
+## Arbitrage Opportunity: When Total Price Doesn't Equal $1
+
+When market trading causes total price to deviate from $1, risk-free profit opportunities emerge.
+
+### 1. Emotional Buying
+
+Breaking news hits the market, some traders impulsively buy large amounts of YES, causing its price to spike.
+
+Imbalanced State:
+0.60 (YES) + 0.35 (NO) = $0.95 (less than $1 by $0.05)
+
+Arbitrage Play:
+* Action: Simultaneously buy 1 share of YES and 1 share of NO.
+* Cost: $0.95
+* Result: Regardless of whether the event happens, your share set will settle at $1.00.
+* Profit: Stable $0.05 profit per set (about 5.2% return).
+
+### 2. Global Time Lag
+
+Major news released during US midnight, American traders react quickly, buying up YES; while Asian traders are still asleep, NO price hasn't updated synchronously.
+
+Imbalanced State:
+0.70 (YES) + 0.33 (NO) = $1.03 (more than $1 by $0.03)
+
+Arbitrage Play:
+* Action: Reverse operation, simultaneously sell 1 share of YES and 1 share of NO.
+* Income: $1.03
+* Result: You only need to return $1.00 at settlement.
+* Profit: Instantly lock in $0.03 profit (about 2.9% return).
+
+### 3. Low Liquidity + Large Order Dump
+
+In many low-volume events, a single large sell order of tens of thousands of dollars can instantly crash the YES price, while NO price can't react in time.
+
+Imbalanced State:
+0.45 (YES) + 0.50 (NO) = $0.95 (less than $1 by $0.05)
+
+Arbitrage Play:
+* Action: Monitoring bots programmatically buy the dumped asset combination.
+* Cost: $0.95
+* Result: Wait for market price to recover or hold to settlement, get $1.00.
+* Profit: Bots capture 5.2% instant profit.
+
+### 4. Cross-Platform Price Spreads
+
+The same event on different prediction platforms (like Polymarket and Kalshi), due to different user bases and liquidity, prices differ.
+
+Imbalanced State:
+* Polymarket: YES $0.80 / NO $0.20 (buy NO)
+* Kalshi: YES $0.75 / NO $0.25 (buy YES)
+
+Arbitrage Play:
+* Action: Buy cheaper NO ($0.20) on Polymarket, simultaneously buy cheaper YES ($0.75) on Kalshi.
+* Total cost: $0.20 + $0.75 = $0.95
+* Result: You've completely covered all outcomes, this cross-platform asset combination must settle at $1.00.
+* Profit: Lock in 5.2% cross-market risk-free profit.
+
+## Summary: The Game Rules Behind Easy Money
+
+Understanding the core of Polymarket arbitrage isn't about personally racing against bots, but about gaining insight into the commonality that exists in any market: efficiency is always generated in the game between rationality and human nature (irrationality).
+
+Every price you see has a game behind it. Now, you can see that game.