trip-optimizer 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# trip-optimizer
+
+Autonomously optimize travel plans using the autoresearch pattern -- an AI-powered CLI that researches, scores, and iteratively improves your itinerary.
+
+支持 **English** 和 **中文（简体中文）** -- 在初始化时选择语言，整个体验随之适配：提示语、生成的行程、研究搜索、评分系统全部使用您选择的语言。
+
+## Install
+
+```bash
+npm install -g trip-optimizer
+```
+
+Or run directly:
+
+```bash
+npx trip-optimizer
+```
+
+## Quick Start
+
+```bash
+trip-optimizer init "Japan 2027"
+cd japan-2027
+trip-optimizer run              # agent mode (default, interactive Claude Code)
+trip-optimizer run --standalone  # direct API calls
+trip-optimizer run --headless    # agent mode, non-interactive
+trip-optimizer dashboard --watch
+trip-optimizer plan --pdf        # generate a formatted PDF itinerary
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `init <name>` | Create a new trip project |
+| `config` | Manage API keys and settings |
+| `profile` | View travel profile |
+| `score` | One-off absolute scoring |
+| `research [city]` | Research sprint |
+| `run` | Start optimization loop (agent mode) |
+| `run --standalone` | Optimization via direct API calls |
+| `run --headless` | Agent mode, non-interactive |
+| `status` | Show progress |
+| `dashboard` | Live optimization dashboard |
+| `chart` | ASCII score chart |
+| `plan` | Pretty-print travel plan |
+| `plan --pdf` | Generate a PDF document |
+| `debrief` | Post-trip feedback |
+| `history` | View past trips |
+
+## How It Works
+
+Trip-optimizer follows the **autoresearch pattern**: it autonomously researches destinations, generates plan mutations, scores results, and keeps only improvements. Each optimization iteration proposes targeted changes -- swapping a restaurant, adjusting timing, adding a hidden-gem activity -- then evaluates whether the change improved the overall plan. Bad mutations are discarded; good ones accumulate.
+
+Scoring uses a **3-pass pipeline**. First, the plan is evaluated across seven weighted dimensions (experience, logistics, food, time management, budget, accommodation, and transit). Then an adversarial critic searches for concrete flaws -- unconfirmed bookings, chain restaurants, vague transit -- and applies penalties. Finally, a holistic adjustment reconciles the dimension scores with the critic's findings into a single composite score.
+
+The system builds **persistent memory** across trips. After each trip, a debrief captures what worked and what didn't. These learnings are stored in `learned.json` and feed back into scoring rubrics and research priorities for future trips, so the optimizer gets smarter over time.
+
+### 语言与本地化
+
+`init` 的第一个问题是语言选择。选择 **中文** 后：
+
+- 所有命令行提示和消息以中文显示
+- 生成的行程、评分标准和计划均以简体中文撰写
+- 研究优先使用中文平台（小红书、大众点评、马蜂窝、携程），而非英文来源
+- 搜索关键词使用中文（本地人推荐、避雷指南、苍蝇馆子），同时辅以英文补充搜索
+- PDF 输出正确渲染中文内容
+
+### Custom Model Support
+
+During `init`, you can optionally configure a custom LLM instead of the default Anthropic/Vertex provider. Any OpenAI-compatible API works -- Kimi (Moonshot), DeepSeek, and others. Custom models run in `--standalone` mode; agent mode always uses Claude Code.
+
+## Requirements
+
+- Node.js 22+
+- One of:
+  - Anthropic API key (via `trip-optimizer config` or `ANTHROPIC_API_KEY`)
+  - Google Cloud Vertex AI (`CLAUDE_CODE_USE_VERTEX=1` + `GOOGLE_CLOUD_PROJECT`)
+  - Custom OpenAI-compatible API (configured during `init`)
+
+## License
+
+MIT

package/dist/chunk-OSZUVWNK.js

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+
+// src/data/config.ts
+import fs from "fs";
+import path2 from "path";
+
+// src/data/paths.ts
+import path from "path";
+import os from "os";
+function getGlobalDir() {
+  return path.join(os.homedir(), ".trip-optimizer");
+}
+function getTripHistoryPath() {
+  return path.join(getGlobalDir(), "trip-history.json");
+}
+function getLearnedPath() {
+  return path.join(getGlobalDir(), "learned.json");
+}
+
+// src/data/config.ts
+var DEFAULT_CONFIG = {
+  provider: "anthropic",
+  api_key: "",
+  language: "en"
+};
+function loadConfig(dir) {
+  const configPath = path2.join(dir ?? getGlobalDir(), "config.json");
+  if (!fs.existsSync(configPath)) return { ...DEFAULT_CONFIG };
+  const loaded = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+  return { ...DEFAULT_CONFIG, ...loaded };
+}
+function saveConfig(config, dir) {
+  const d = dir ?? getGlobalDir();
+  fs.mkdirSync(d, { recursive: true });
+  fs.writeFileSync(path2.join(d, "config.json"), JSON.stringify(config, null, 2));
+}
+
+// src/i18n.ts
+var messages = {
+  // Init flow
+  "init.title": { en: "trip-optimizer", zh: "trip-optimizer" },
+  "init.language": { en: "Language / \u8BED\u8A00:", zh: "\u8BED\u8A00 / Language:" },
+  "init.first_time": { en: "First time? Let's set up your profile.", zh: "\u9996\u6B21\u4F7F\u7528\uFF1F\u8BA9\u6211\u4EEC\u8BBE\u7F6E\u60A8\u7684\u4E2A\u4EBA\u8D44\u6599\u3002" },
+  "init.vertex_detected": { en: "Using Vertex AI (detected from environment).", zh: "\u4F7F\u7528 Vertex AI\uFF08\u4ECE\u73AF\u5883\u53D8\u91CF\u68C0\u6D4B\uFF09\u3002" },
+  "init.api_key": { en: "Anthropic API key:", zh: "Anthropic API \u5BC6\u94A5\uFF1A" },
+  "init.api_key_saved": { en: "API key saved.", zh: "API \u5BC6\u94A5\u5DF2\u4FDD\u5B58\u3002" },
+  "init.api_key_required": { en: "API key is required", zh: "API \u5BC6\u94A5\u4E3A\u5FC5\u586B\u9879" },
+  "init.model_override": { en: "Use a different LLM? (e.g., Kimi, DeepSeek)", zh: "\u4F7F\u7528\u5176\u4ED6\u5927\u6A21\u578B\uFF1F\uFF08\u5982 Kimi\u3001DeepSeek\uFF09" },
+  "init.model_override_yes": { en: "Yes, configure a custom model", zh: "\u662F\uFF0C\u914D\u7F6E\u81EA\u5B9A\u4E49\u6A21\u578B" },
+  "init.model_override_no": { en: "No, use default", zh: "\u5426\uFF0C\u4F7F\u7528\u9ED8\u8BA4" },
+  "init.model_name": { en: "Model name (e.g., moonshot-v1-128k):", zh: "\u6A21\u578B\u540D\u79F0\uFF08\u5982 moonshot-v1-128k\uFF09\uFF1A" },
+  "init.model_base_url": { en: "API base URL (e.g., https://api.moonshot.cn/v1):", zh: "API \u5730\u5740\uFF08\u5982 https://api.moonshot.cn/v1\uFF09\uFF1A" },
+  "init.model_api_key": { en: "API key for this model:", zh: "\u8BE5\u6A21\u578B\u7684 API \u5BC6\u94A5\uFF1A" },
+  "init.model_saved": { en: "Custom model configured.", zh: "\u81EA\u5B9A\u4E49\u6A21\u578B\u5DF2\u914D\u7F6E\u3002" },
+  "init.model_removed": { en: "Custom model removed. Using default provider.", zh: "\u81EA\u5B9A\u4E49\u6A21\u578B\u5DF2\u79FB\u9664\uFF0C\u4F7F\u7528\u9ED8\u8BA4\u63D0\u4F9B\u8005\u3002" },
+  "init.model_keep_or_change": { en: "Custom model settings:", zh: "\u81EA\u5B9A\u4E49\u6A21\u578B\u8BBE\u7F6E\uFF1A" },
+  "init.model_keep": { en: "Keep current settings", zh: "\u4FDD\u6301\u5F53\u524D\u8BBE\u7F6E" },
+  "init.model_edit": { en: "Edit model / API key / URL", zh: "\u7F16\u8F91\u6A21\u578B / API \u5BC6\u94A5 / \u5730\u5740" },
+  "init.model_remove": { en: "Remove custom model (use default)", zh: "\u79FB\u9664\u81EA\u5B9A\u4E49\u6A21\u578B\uFF08\u4F7F\u7528\u9ED8\u8BA4\uFF09" },
+  "init.model_note": { en: "Note: Custom models only work in standalone mode (trip-optimizer run --standalone).", zh: "\u6CE8\u610F\uFF1A\u81EA\u5B9A\u4E49\u6A21\u578B\u4EC5\u5728\u72EC\u7ACB\u6A21\u5F0F\u4E0B\u8FD0\u884C\uFF08trip-optimizer run --standalone\uFF09\u3002" },
+  // Profile setup
+  "profile.loyalty": { en: "Hotel loyalty program:", zh: "\u9152\u5E97\u4F1A\u5458\u8BA1\u5212\uFF1A" },
+  "profile.dietary": { en: "Dietary restrictions (Space to select, Enter to confirm):", zh: "\u996E\u98DF\u9650\u5236\uFF08\u7A7A\u683C\u9009\u62E9\uFF0C\u56DE\u8F66\u786E\u8BA4\uFF09\uFF1A" },
+  // Trip questions
+  "trip.start_date": { en: "Start date (YYYY-MM-DD):", zh: "\u51FA\u53D1\u65E5\u671F\uFF08YYYY-MM-DD\uFF09\uFF1A" },
+  "trip.end_date": { en: "End date (YYYY-MM-DD):", zh: "\u7ED3\u675F\u65E5\u671F\uFF08YYYY-MM-DD\uFF09\uFF1A" },
+  "trip.travelers": { en: "Number of travelers:", zh: "\u51FA\u884C\u4EBA\u6570\uFF1A" },
+  "trip.origin": { en: "Departing from (city):", zh: "\u51FA\u53D1\u57CE\u5E02\uFF1A" },
+  "trip.cities": { en: "Cities in order (comma-separated):", zh: "\u57CE\u5E02\u987A\u5E8F\uFF08\u9017\u53F7\u5206\u9694\uFF09\uFF1A" },
+  "trip.cities_validate": { en: "Enter at least one city", zh: "\u8BF7\u81F3\u5C11\u8F93\u5165\u4E00\u4E2A\u57CE\u5E02" },
+  "trip.budget": { en: "Total budget (USD):", zh: "\u603B\u9884\u7B97\uFF08USD\uFF09\uFF1A" },
+  "trip.vibes": { en: "Pick your vibes (Space to select, Enter to confirm):", zh: "\u9009\u62E9\u65C5\u884C\u98CE\u683C\uFF08\u7A7A\u683C\u9009\u62E9\uFF0C\u56DE\u8F66\u786E\u8BA4\uFF09\uFF1A" },
+  "trip.anti_patterns": { en: "Anything to avoid? (comma-separated, or press Enter to skip):", zh: "\u6709\u4EC0\u4E48\u8981\u907F\u514D\u7684\uFF1F\uFF08\u9017\u53F7\u5206\u9694\uFF0C\u6216\u6309\u56DE\u8F66\u8DF3\u8FC7\uFF09\uFF1A" },
+  // Vibe choices
+  "vibe.wandering": { en: "Wandering & exploring", zh: "\u6F2B\u6B65\u63A2\u7D22" },
+  "vibe.food": { en: "Food & culinary", zh: "\u7F8E\u98DF\u4E4B\u65C5" },
+  "vibe.culture": { en: "Culture & arts", zh: "\u6587\u5316\u827A\u672F" },
+  "vibe.nature": { en: "Nature & outdoors", zh: "\u81EA\u7136\u6237\u5916" },
+  "vibe.adventure": { en: "Adventure & thrills", zh: "\u5192\u9669\u523A\u6FC0" },
+  "vibe.relaxation": { en: "Relaxation & wellness", zh: "\u4F11\u95F2\u517B\u751F" },
+  "vibe.nightlife": { en: "Nightlife & entertainment", zh: "\u591C\u751F\u6D3B\u5A31\u4E50" },
+  "vibe.history": { en: "History & heritage", zh: "\u5386\u53F2\u4EBA\u6587" },
+  "vibe.shopping": { en: "Shopping", zh: "\u8D2D\u7269" },
+  "vibe.family": { en: "Family-friendly", zh: "\u4EB2\u5B50\u6E38" },
+  "vibe.romantic": { en: "Romantic", zh: "\u6D6A\u6F2B\u4E4B\u65C5" },
+  // Edit flow
+  "edit.current_settings": { en: "Current settings:", zh: "\u5F53\u524D\u8BBE\u7F6E\uFF1A" },
+  "edit.what_to_do": { en: "What would you like to do?", zh: "\u60A8\u60F3\u505A\u4EC0\u4E48\uFF1F" },
+  "edit.regenerate": { en: "Regenerate with same settings", zh: "\u4F7F\u7528\u76F8\u540C\u8BBE\u7F6E\u91CD\u65B0\u751F\u6210" },
+  "edit.edit_fields": { en: "Edit specific fields", zh: "\u7F16\u8F91\u7279\u5B9A\u5B57\u6BB5" },
+  "edit.restart": { en: "Start over from scratch", zh: "\u4ECE\u5934\u5F00\u59CB" },
+  "edit.which_fields": { en: "Which fields to edit? (Space to select, Enter to confirm):", zh: "\u7F16\u8F91\u54EA\u4E9B\u5B57\u6BB5\uFF1F\uFF08\u7A7A\u683C\u9009\u62E9\uFF0C\u56DE\u8F66\u786E\u8BA4\uFF09\uFF1A" },
+  // Field labels
+  "field.dates": { en: "Dates", zh: "\u65E5\u671F" },
+  "field.travelers": { en: "Travelers", zh: "\u4EBA\u6570" },
+  "field.origin": { en: "Origin", zh: "\u51FA\u53D1\u5730" },
+  "field.cities": { en: "Cities", zh: "\u57CE\u5E02" },
+  "field.budget": { en: "Budget", zh: "\u9884\u7B97" },
+  "field.vibes": { en: "Vibes", zh: "\u98CE\u683C" },
+  "field.anti_patterns": { en: "Anti-patterns", zh: "\u907F\u514D\u4E8B\u9879" },
+  // Progress
+  "progress.generating_rubrics": { en: "Generating scoring rubrics...", zh: "\u6B63\u5728\u751F\u6210\u8BC4\u5206\u6807\u51C6..." },
+  "progress.rubrics_done": { en: "Scoring rubrics generated", zh: "\u8BC4\u5206\u6807\u51C6\u5DF2\u751F\u6210" },
+  "progress.rubrics_fail": { en: "Failed to generate scoring rubrics", zh: "\u8BC4\u5206\u6807\u51C6\u751F\u6210\u5931\u8D25" },
+  "progress.generating_plan": { en: "Generating initial plan...", zh: "\u6B63\u5728\u751F\u6210\u521D\u59CB\u884C\u7A0B..." },
+  "progress.plan_done": { en: "Initial plan generated", zh: "\u521D\u59CB\u884C\u7A0B\u5DF2\u751F\u6210" },
+  "progress.plan_fail": { en: "Failed to generate initial plan", zh: "\u521D\u59CB\u884C\u7A0B\u751F\u6210\u5931\u8D25" },
+  "progress.creating_project": { en: "Creating trip project...", zh: "\u6B63\u5728\u521B\u5EFA\u65C5\u884C\u9879\u76EE..." },
+  "progress.project_created": { en: "Trip project created at", zh: "\u65C5\u884C\u9879\u76EE\u5DF2\u521B\u5EFA\u4E8E" },
+  // Next steps
+  "next.title": { en: "Next steps:", zh: "\u4E0B\u4E00\u6B65\uFF1A" },
+  "next.review": { en: "# Review constraints.yaml and rubrics.yaml", zh: "# \u67E5\u770B constraints.yaml \u548C rubrics.yaml" },
+  // Errors
+  "error.provider_fail": { en: "Failed to create LLM provider", zh: "LLM \u63D0\u4F9B\u8005\u521B\u5EFA\u5931\u8D25" },
+  "error.model_check": { en: "Check that your model is available", zh: "\u8BF7\u68C0\u67E5\u60A8\u7684\u6A21\u578B\u662F\u5426\u53EF\u7528" },
+  "error.auth_check": { en: 'Check your authentication: run "gcloud auth application-default login"', zh: '\u8BF7\u68C0\u67E5\u8BA4\u8BC1\uFF1A\u8FD0\u884C "gcloud auth application-default login"' }
+};
+var currentLanguage = "en";
+function setLanguage(lang) {
+  currentLanguage = lang;
+}
+function getLanguage() {
+  return currentLanguage;
+}
+function t(key) {
+  const entry = messages[key];
+  return entry[currentLanguage] || entry.en;
+}
+function getLlmLanguageInstruction() {
+  if (currentLanguage === "zh") {
+    return "\n\nIMPORTANT: Generate ALL output in Chinese (Simplified Chinese / \u7B80\u4F53\u4E2D\u6587). All descriptions, recommendations, and commentary must be written in Chinese.";
+  }
+  return "";
+}
+
+// src/generators/program.ts
+function generateProgram(constraints, config) {
+  const hasSearchApi = !!config.search_api?.api_key;
+  const isZh = getLanguage() === "zh";
+  const researchSources = isZh ? `### \u7814\u7A76\u6765\u6E90\uFF08\u6309\u4F18\u5148\u7EA7\u6392\u5E8F\uFF09
+
+1. **\u6D4F\u89C8\u5668\u7814\u7A76**\uFF08\u5982\u679C agent-browser \u6280\u80FD\u53EF\u7528\uFF09\uFF1A
+   - \u4F7F\u7528 \`agent-browser\` \u6280\u80FD\u8BBF\u95EE\u5927\u4F17\u70B9\u8BC4\u3001\u5C0F\u7EA2\u4E66\u3001\u9A6C\u8702\u7A9D\u3001\u643A\u7A0B\u3001Google Maps
+   - \u63D0\u53D6\u8BC4\u5206\u3001\u8BC4\u8BBA\u6570\u91CF\u3001\u5F53\u5B63\u83DC\u5355\u3001\u672C\u5730\u4EBA\u63A8\u8350
+   - \u8FD9\u662F\u6700\u771F\u5B9E\u7684\u5B9E\u65F6\u6570\u636E\u6765\u6E90
+   - \u4F18\u5148\u641C\u7D22\u4E2D\u6587\u5E73\u53F0\uFF08\u5C0F\u7EA2\u4E66\u3001\u5927\u4F17\u70B9\u8BC4\u3001\u9A6C\u8702\u7A9D\uFF09\uFF0C\u56E0\u4E3A\u672C\u5730\u4EBA\u7684\u63A8\u8350\u66F4\u53EF\u9760
+
+${hasSearchApi ? `2. **\u7F51\u7EDC\u641C\u7D22 API**\uFF08\u5DF2\u914D\u7F6E\uFF09\uFF1A
+   - \u641C\u7D22 "[\u57CE\u5E02] \u672C\u5730\u4EBA\u63A8\u8350 \u9690\u85CF\u7F8E\u98DF"
+   - \u641C\u7D22 "[\u57CE\u5E02] \u907F\u96F7 \u8E29\u5751 \u6E38\u5BA2\u9677\u9631"
+   - \u641C\u7D22 "[\u57CE\u5E02] \u5C0F\u4F17\u666F\u70B9 \u5F53\u5730\u4EBA\u624D\u77E5\u9053"
+   - \u641C\u7D22 "[\u57CE\u5E02] \u5F53\u5B63\u7279\u8272 \u65F6\u4EE4\u7F8E\u98DF"
+   - \u540C\u65F6\u641C\u7D22\u4E2D\u82F1\u6587\u5173\u952E\u8BCD\u4EE5\u83B7\u53D6\u66F4\u5168\u9762\u7684\u7ED3\u679C
+
+3. **LLM \u77E5\u8BC6**\uFF08\u5907\u9009\uFF09\uFF1A` : `2. **LLM \u77E5\u8BC6**\uFF08\u4E3B\u8981\u6765\u6E90\uFF09\uFF1A
+`}   - \u4F7F\u7528\u8BAD\u7EC3\u6570\u636E\u83B7\u53D6\u6D3B\u52A8\u548C\u9910\u5385\u63A8\u8350
+   - \u6807\u8BB0\u6765\u6E90\u4E3A "llm_knowledge" \u4EE5\u4FBF\u8BC4\u5206\u5668\u964D\u4F4E\u6743\u91CD
+   - \u5BF9\u77E5\u540D\u76EE\u7684\u5730\u6548\u679C\u597D\uFF0C\u5BF9\u51B7\u95E8\u5730\u70B9\u6548\u679C\u8F83\u5DEE` : `### Research Sources (in priority order)
+
+1. **Browser research** (if agent-browser skill is available):
+   - Invoke the \`agent-browser\` skill to visit Google Maps, Dianping, Xiaohongshu, TripAdvisor
+   - Extract ratings, review counts, seasonal menus
+   - This gives real-time, ground-truth data
+
+${hasSearchApi ? `2. **Web search API** (configured):
+   - Use WebSearch tool for "[city] hidden gems locals recommend"
+   - Search for "[city] overrated tourist traps to skip"
+   - Search for "[city] best street food locals recommend"
+   - Search for seasonal factors
+
+3. **LLM knowledge** (fallback):` : `2. **LLM knowledge** (primary):
+`}   - Use training data for activity and restaurant recommendations
+   - Flag entries as source: "llm_knowledge" so scorer weights them lower
+   - Good for major destinations, weaker for obscure ones`;
+  const researchQueries = isZh ? `### \u7814\u7A76\u641C\u7D22\u5173\u952E\u8BCD
+- "[\u57CE\u5E02] \u672C\u5730\u4EBA\u63A8\u8350 \u5C0F\u4F17\u666F\u70B9"
+- "[\u57CE\u5E02] \u907F\u96F7\u6307\u5357 \u6E38\u5BA2\u9677\u9631"
+- "[\u57CE\u5E02] \u5FC5\u5403\u7F8E\u98DF \u82CD\u8747\u9986\u5B50 \u672C\u5730\u4EBA\u6392\u961F"
+- "[\u57CE\u5E02] \u503C\u5F97\u901B\u7684\u8857\u533A City Walk"
+- "[\u57CE\u5E02] [\u5B63\u8282] \u5F53\u5B63\u7279\u8272 \u65F6\u4EE4\u63A8\u8350"
+- "[\u57CE\u5E02] \u6DF1\u5EA6\u6E38 \u4E0D\u5728\u653B\u7565\u4E0A\u7684\u4F53\u9A8C"
+- "[City] hidden gems locals only"\uFF08\u82F1\u6587\u8865\u5145\u641C\u7D22\uFF09
+- "[City] authentic local food NOT tourist"\uFF08\u82F1\u6587\u8865\u5145\u641C\u7D22\uFF09` : `### Research Query Patterns
+- "[City] hidden gems locals only"
+- "[City] overrated tourist traps to skip"
+- "[City] best street food locals recommend"
+- "[City] atmospheric neighborhoods to walk"
+- "[City] what to do in [season] seasonal"
+- "[City] authentic experiences not on TripAdvisor"`;
+  const outputLanguage = isZh ? `
+## \u8F93\u51FA\u8BED\u8A00
+
+\u6240\u6709\u8F93\u51FA\uFF08plan.md\u3001activities_db.json \u4E2D\u7684\u63CF\u8FF0\u3001commit messages\uFF09\u90FD\u5FC5\u987B\u4F7F\u7528\u7B80\u4F53\u4E2D\u6587\u3002
+` : "";
+  return `# trip-optimizer Agent Instructions
+
+## Setup
+1. Read \`constraints.yaml\` for fixed parameters and preferences
+2. Read the current \`plan.md\` as baseline
+3. Read \`activities_db.json\` (may be empty on first run)
+4. Run scoring on the baseline plan, record as initial score
+5. Confirm setup, then begin
+
+## Phase 1: Research Sprint
+
+Before mutating anything, build knowledge. For each city in the plan:
+
+${researchSources}
+
+${researchQueries}
+
+After researching, add all findings to \`activities_db.json\` with scores and sources.
+Git commit the updated database.
+${outputLanguage}
+## Phase 2: Optimization Loop
+
+\`\`\`
+LOOP FOREVER:
+
+1. Pick a mutation type (rotate through these):
+   a. SWAP \u2014 replace an activity with a higher-scored alternative from activities_db
+   b. REALLOCATE \u2014 move a day between cities (within min/max bounds)
+   c. REORDER \u2014 rearrange a day's activities for better geographic clustering
+   d. UPGRADE \u2014 replace a restaurant with a more authentic option
+   e. SIMPLIFY \u2014 remove a low-scoring activity, leave free wandering time
+   f. RESEARCH \u2014 search for new options in the weakest-scoring city,
+      add to activities_db, then attempt a swap
+
+2. Make ONE change to plan.md
+3. Git commit with descriptive message
+4. Score the new plan (comparative mode for most iterations, absolute every 10th)
+5. If score improved \u2192 keep the commit
+6. If score equal or worse \u2192 git reset --hard HEAD~1
+7. Log to results.tsv (tab-separated):
+   iteration, commit, score_before, score_after, delta, status, mutation_type, description
+8. NEVER STOP \u2014 run until interrupted
+\`\`\`
+
+## Mutation Guidelines
+
+- **One mutation per iteration.** Don't change multiple things at once.
+- **Free time is valuable.** Empty afternoons for wandering can score higher than mediocre activities.
+- **Respect geographic clustering.** Don't zigzag across the city.
+- **Respect day bounds.** When reallocating days, stay within min/max in constraints.yaml.
+- **Transit days are partial days.** A day with 5+ hours transit should not have full activities.
+- **Research when stuck.** If 5+ consecutive discards, trigger a RESEARCH mutation.
+
+## What You CANNOT Do
+
+- Add or remove cities from the route
+- Change the city ordering
+- Modify constraints.yaml or rubrics.yaml
+- Exceed min/max day bounds per city
+- Schedule activities during transit time
+${constraints.hard_requirements.map((r) => `- Violate: ${r}`).join("\n")}
+
+## Crash/Failure Handling
+
+- If scoring fails, revert and log as crash
+- If 10 consecutive discards, try REALLOCATE or RESEARCH
+- If score plateaus for 20+ iterations, shift to RESEARCH phase
+- results.tsv survives git resets (it's gitignored)
+
+## Context Management
+
+- Write long outputs to files, don't flood context
+- Write research to activities_db.json immediately
+- Read results.tsv periodically to avoid repeating failed mutations
+`;
+}
+
+export {
+  getGlobalDir,
+  getTripHistoryPath,
+  getLearnedPath,
+  loadConfig,
+  saveConfig,
+  setLanguage,
+  t,
+  getLlmLanguageInstruction,
+  generateProgram
+};