empire-cli 0.1.0 → 0.2.0

package/README.md

@@ -1,47 +1,17 @@
 # ⚔️ Empire CLI 👑
 
+[![npm version](https://img.shields.io/npm/v/empire-cli)](https://www.npmjs.com/package/empire-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 > **Status: Early MVP** — Core gameplay works. AI game master (Gemini/Ollama/Claude) coming soon.
 
 A CLI turn-based strategy RPG where you build armies, expand your empire, and conquer the world. Open source, runs in any terminal.
 
-## Screenshot
+## Screenshots
 
-```
-  ╔════════════════════════════╗
-  ║  ⚔️  E M P I R E  CLI  👑  ║
-  ╚════════════════════════════╝
-
-  👑 Iron Legion  —  Turn 1
-  💰 20  🍖 10  🪵 5  🪨 15
-  ⚔️  Armies: 5  |  🚩 Territories: 2/8
-
-  World Map:
-  🏰 Northkeep      Iron Legion ⚔️  3 ★
-     ↔ Iron Hills, Greenwood
-  ⛰️  Iron Hills     Iron Legion ⚔️  2 ★
-     ↔ Northkeep, Crossroads
-  🌲 Greenwood      Green Pact ⚔️  2
-     ↔ Northkeep, Crossroads, Silver Bay
-  🌾 Crossroads     Unclaimed
-     ↔ Iron Hills, Greenwood, Desert Gate, Stonehaven
-  🏰 Silver Bay     Green Pact ⚔️  3
-     ↔ Greenwood, Stonehaven
-  ⛰️  Dragon Peak    Void Covenant ⚔️  4
-     ↔ Stonehaven
-
-  Turn 1 [3/3 actions] > recruit northkeep 2
-  🛡️  Recruited 2 units in Northkeep. (💰-6 🍖-4)
-
-  Turn 1 [2/3 actions] > attack iron crossroads
-  🔥 Battle: Iron Hills (5) → Crossroads (0)
-  Decisive victory! The defenders are routed!
-  🚩 You captured Crossroads!
-
-  --- End of Turn 1 ---
-  🔥 Enemy Actions:
-  Green Pact recruited 3 units in Greenwood
-  Sand Empire attacks Stonehaven from Desert Gate!
-```
+![Menu](assets/sc-menu.png)
+
+![Gameplay](assets/sc-gameplay.png)
 
 ## Quick Start
 
@@ -64,8 +34,9 @@ npm start
 3. "info northkeep" — inspect a territory
 4. "recruit northkeep 3" — train 3 units (costs 3💰 + 2🍖 each)
 5. "move northkeep greenwood 3" — march 3 units to Greenwood
-6. "attack greenwood silver" — attack Silver Bay from Greenwood
-7. "next" — end your turn (or use all 3 actions, auto-advances)
+6. "build northkeep walls" — build walls for defense (costs 🪵🪨)
+7. "attack greenwood silver" — attack Silver Bay from Greenwood
+8. "next" — end your turn (or use all 3 actions, auto-advances)
 8. Watch enemy factions react — then plan your next move!
 ```
 
@@ -83,6 +54,7 @@ You get **3 actions per turn**. `look`, `info`, `status`, `help`, `save` are fre
 | `move <from> <to> [n]` | Move n units between territories (all if omitted) |
 | `recruit <territory> <n>` | Recruit n units at a territory |
 | `attack <from> <to>` | Attack enemy territory from yours |
+| `build <territory> <type>` | Build walls/barracks/market |
 | `next` | End turn early |
 | `save [slot]` | Save game |
 | `help` | Show commands |
@@ -101,8 +73,16 @@ You get **3 actions per turn**. `look`, `info`, `status`, `help`, `save` are fre
 
 - 💰 **Gold** — Recruit armies (3 per unit)
 - 🍖 **Food** — Recruit + army upkeep (2 per unit)
-- 🪵 **Wood** — Future: buildings
-- 🪨 **Stone** — Future: fortifications
+- 🪵 **Wood** — Build structures
+- 🪨 **Stone** — Build structures
+
+## Buildings
+
+| Building | Cost | Effect |
+|----------|------|--------|
+| 🧱 Walls | 10🪵 15🪨 | +0.3 defense bonus |
+| 🏛️ Barracks | 8🪵 5🪨 | Recruit costs 2💰 instead of 3💰 |
+| 🏪 Market | 10💰 5🪵 3🪨 | +2💰 income per turn |
 
 ## Roadmap
 
@@ -114,9 +94,9 @@ You get **3 actions per turn**. `look`, `info`, `status`, `help`, `save` are fre
 - [x] Action limit per turn (3 actions)
 - [ ] AI Game Master (Gemini free tier / Ollama / Claude) — dynamic narration
 - [ ] Diplomacy system (alliances, trade, peace)
-- [ ] Buildings (walls, barracks, markets)
+- [x] Buildings (walls, barracks, markets)
 - [ ] More maps & factions
-- [ ] npm package (`npx empire-cli`)
+- [x] npm package (`npx empire-cli`) [![npm](https://img.shields.io/npm/v/empire-cli)](https://www.npmjs.com/package/empire-cli)
 
 ## Tech Stack
 

package/dist/data/default-world-map.js

@@ -16,6 +16,7 @@ export const DEFAULT_TERRITORIES = [
         armies: 3,
         resources: { gold: 4, food: 2, wood: 1, stone: 2 },
         adjacentTo: ['iron_hills', 'greenwood'],
+        buildings: [],
     },
     {
         id: 'iron_hills',
@@ -25,6 +26,7 @@ export const DEFAULT_TERRITORIES = [
         armies: 2,
         resources: { gold: 2, food: 1, wood: 0, stone: 4 },
         adjacentTo: ['northkeep', 'crossroads'],
+        buildings: [],
     },
     {
         id: 'greenwood',
@@ -34,6 +36,7 @@ export const DEFAULT_TERRITORIES = [
         armies: 2,
         resources: { gold: 1, food: 3, wood: 4, stone: 0 },
         adjacentTo: ['northkeep', 'crossroads', 'silver_bay'],
+        buildings: [],
     },
     {
         id: 'crossroads',
@@ -43,6 +46,7 @@ export const DEFAULT_TERRITORIES = [
         armies: 0,
         resources: { gold: 2, food: 2, wood: 1, stone: 1 },
         adjacentTo: ['iron_hills', 'greenwood', 'desert_gate', 'stonehaven'],
+        buildings: [],
     },
     {
         id: 'desert_gate',
@@ -52,6 +56,7 @@ export const DEFAULT_TERRITORIES = [
         armies: 2,
         resources: { gold: 3, food: 1, wood: 0, stone: 2 },
         adjacentTo: ['crossroads'],
+        buildings: [],
     },
     {
         id: 'silver_bay',
@@ -61,6 +66,7 @@ export const DEFAULT_TERRITORIES = [
         armies: 3,
         resources: { gold: 5, food: 2, wood: 1, stone: 1 },
         adjacentTo: ['greenwood', 'stonehaven'],
+        buildings: [],
     },
     {
         id: 'stonehaven',
@@ -70,6 +76,7 @@ export const DEFAULT_TERRITORIES = [
         armies: 2,
         resources: { gold: 2, food: 1, wood: 0, stone: 5 },
         adjacentTo: ['crossroads', 'silver_bay', 'dragon_peak'],
+        buildings: [],
     },
     {
         id: 'dragon_peak',
@@ -79,6 +86,7 @@ export const DEFAULT_TERRITORIES = [
         armies: 4,
         resources: { gold: 1, food: 0, wood: 0, stone: 6 },
         adjacentTo: ['stonehaven'],
+        buildings: [],
     },
 ];
 export const DEFAULT_FACTIONS = [

package/dist/engine/ai-turn-processor.js

@@ -45,7 +45,7 @@ export function runAiTurns(state) {
                     continue;
                 if (attackerUnits < defenderUnits && faction.personality !== 'aggressive')
                     continue;
-                const result = resolveCombat(attackerUnits, 80, defenderUnits, 80, adj.type);
+                const result = resolveCombat(attackerUnits, 80, defenderUnits, 80, adj.type, adj);
                 log.push(`${faction.name} attacks ${adj.name} from ${territory.name}!`);
                 const attackerArmy = findArmyInTerritory(faction.id, territoryId, state.armies);
                 if (attackerArmy)

package/dist/engine/army-manager.js

@@ -1,6 +1,7 @@
 // Army recruitment, movement, and validation logic
 import { canAfford, deductResources } from './resource-calculator.js';
-const RECRUIT_COST_PER_UNIT = { gold: 3, food: 2, wood: 0, stone: 0 };
+import { getRecruitGoldCost } from './building-manager.js';
+const RECRUIT_FOOD_PER_UNIT = 2;
 const DEFAULT_MORALE = 80;
 let armyIdCounter = 1;
 function generateArmyId() {
@@ -17,9 +18,10 @@ export function recruitArmy(faction, territory, units, armies) {
     if (units < 1) {
         return 'Must recruit at least 1 unit.';
     }
+    const goldPerUnit = getRecruitGoldCost(territory);
     const totalCost = {
-        gold: RECRUIT_COST_PER_UNIT.gold * units,
-        food: RECRUIT_COST_PER_UNIT.food * units,
+        gold: goldPerUnit * units,
+        food: RECRUIT_FOOD_PER_UNIT * units,
     };
     if (!canAfford(faction, totalCost)) {
         return `Not enough resources. Need ${totalCost.gold} gold and ${totalCost.food} food.`;

package/dist/engine/building-manager.d.ts

@@ -0,0 +1,25 @@
+import type { BuildingType, Faction, Territory, Resources } from '../game-types.js';
+export interface BuildingDef {
+    type: BuildingType;
+    label: string;
+    icon: string;
+    cost: Partial<Resources>;
+    description: string;
+}
+export declare const BUILDINGS: Record<BuildingType, BuildingDef>;
+/**
+ * Build a structure in a territory. Returns error message or null on success.
+ */
+export declare function buildStructure(faction: Faction, territory: Territory, buildingType: BuildingType): string | null;
+/**
+ * Get defense bonus from buildings in a territory (added to terrain bonus).
+ */
+export declare function getBuildingDefenseBonus(territory: Territory): number;
+/**
+ * Get recruit cost discount from barracks.
+ */
+export declare function getRecruitGoldCost(territory: Territory): number;
+/**
+ * Get bonus gold income from market.
+ */
+export declare function getMarketGoldBonus(territory: Territory): number;

package/dist/engine/building-manager.js

@@ -0,0 +1,52 @@
+// Building construction logic: walls (defense), barracks (cheaper recruits), market (gold income)
+export const BUILDINGS = {
+    walls: { type: 'walls', label: 'Walls', icon: '🧱', cost: { wood: 10, stone: 15 }, description: '+0.3 defense bonus' },
+    barracks: { type: 'barracks', label: 'Barracks', icon: '🏛️', cost: { wood: 8, stone: 5 }, description: 'recruit costs 2g instead of 3g' },
+    market: { type: 'market', label: 'Market', icon: '🏪', cost: { gold: 10, wood: 5, stone: 3 }, description: '+2 gold income/turn' },
+};
+/**
+ * Build a structure in a territory. Returns error message or null on success.
+ */
+export function buildStructure(faction, territory, buildingType) {
+    if (territory.owner !== faction.id) {
+        return `You don't own ${territory.name}.`;
+    }
+    const def = BUILDINGS[buildingType];
+    if (!def)
+        return `Unknown building: ${buildingType}. Available: walls, barracks, market`;
+    if (territory.buildings.includes(buildingType)) {
+        return `${territory.name} already has ${def.label}.`;
+    }
+    // Check cost
+    const cost = def.cost;
+    if ((cost.gold ?? 0) > faction.gold)
+        return `Not enough gold. Need ${cost.gold}, have ${faction.gold}.`;
+    if ((cost.wood ?? 0) > faction.wood)
+        return `Not enough wood. Need ${cost.wood}, have ${faction.wood}.`;
+    if ((cost.stone ?? 0) > faction.stone)
+        return `Not enough stone. Need ${cost.stone}, have ${faction.stone}.`;
+    // Deduct resources
+    faction.gold -= cost.gold ?? 0;
+    faction.wood -= cost.wood ?? 0;
+    faction.stone -= cost.stone ?? 0;
+    territory.buildings.push(buildingType);
+    return null;
+}
+/**
+ * Get defense bonus from buildings in a territory (added to terrain bonus).
+ */
+export function getBuildingDefenseBonus(territory) {
+    return territory.buildings.includes('walls') ? 0.3 : 0;
+}
+/**
+ * Get recruit cost discount from barracks.
+ */
+export function getRecruitGoldCost(territory) {
+    return territory.buildings.includes('barracks') ? 2 : 3;
+}
+/**
+ * Get bonus gold income from market.
+ */
+export function getMarketGoldBonus(territory) {
+    return territory.buildings.includes('market') ? 2 : 0;
+}

package/dist/engine/combat-resolver.d.ts

@@ -1,9 +1,9 @@
-import type { CombatResult, TerritoryType } from '../game-types.js';
+import type { CombatResult, TerritoryType, Territory } from '../game-types.js';
 /**
  * Resolve combat between attacker and defender armies.
  * Uses a power ratio formula to determine outcome and casualties.
  */
-export declare function resolveCombat(attackerUnits: number, attackerMorale: number, defenderUnits: number, defenderMorale: number, terrain: TerritoryType): CombatResult;
+export declare function resolveCombat(attackerUnits: number, attackerMorale: number, defenderUnits: number, defenderMorale: number, terrain: TerritoryType, defenderTerritory?: Territory): CombatResult;
 /**
  * Simulate AI faction auto-attack decision: returns true if AI should attack.
  */

package/dist/engine/combat-resolver.js

@@ -1,4 +1,5 @@
 // Combat resolution engine: calculates battle outcomes based on units, morale, terrain
+import { getBuildingDefenseBonus } from './building-manager.js';
 // Terrain defense bonuses (multiplier on defender power)
 const TERRAIN_BONUS = {
     plains: 1.0,
@@ -10,13 +11,17 @@ const TERRAIN_BONUS = {
  * Resolve combat between attacker and defender armies.
  * Uses a power ratio formula to determine outcome and casualties.
  */
-export function resolveCombat(attackerUnits, attackerMorale, defenderUnits, defenderMorale, terrain) {
+export function resolveCombat(attackerUnits, attackerMorale, defenderUnits, defenderMorale, terrain, defenderTerritory) {
     const log = [];
     const terrainBonus = TERRAIN_BONUS[terrain];
+    const wallBonus = defenderTerritory ? getBuildingDefenseBonus(defenderTerritory) : 0;
+    const totalDefBonus = terrainBonus + wallBonus;
     const attackPower = attackerUnits * (attackerMorale / 100);
-    const defensePower = defenderUnits * (defenderMorale / 100) * terrainBonus;
+    const defensePower = defenderUnits * (defenderMorale / 100) * totalDefBonus;
     log.push(`Attack power: ${attackPower.toFixed(1)} vs Defense power: ${defensePower.toFixed(1)}`);
     log.push(`Terrain (${terrain}) gives defender x${terrainBonus} bonus`);
+    if (wallBonus > 0)
+        log.push(`Walls give defender +${wallBonus} bonus`);
     const ratio = attackPower / (defensePower || 1);
     let outcome;
     let attackerCasualties;

package/dist/engine/resource-calculator.js

@@ -1,4 +1,5 @@
 // Resource collection and upkeep calculations for each faction per turn
+import { getMarketGoldBonus } from './building-manager.js';
 const ARMY_FOOD_UPKEEP = 1; // food per army unit per turn
 const ARMY_GOLD_UPKEEP = 0; // gold per army unit (free for now)
 /**
@@ -10,7 +11,7 @@ export function collectResources(faction, territories) {
         const territory = territories.get(territoryId);
         if (!territory)
             continue;
-        income.gold += territory.resources.gold;
+        income.gold += territory.resources.gold + getMarketGoldBonus(territory);
         income.food += territory.resources.food;
         income.wood += territory.resources.wood;
         income.stone += territory.resources.stone;

package/dist/game-types.d.ts

@@ -1,4 +1,5 @@
 export type TerritoryType = 'plains' | 'forest' | 'mountain' | 'city';
+export type BuildingType = 'walls' | 'barracks' | 'market';
 export type FactionPersonality = 'aggressive' | 'defensive' | 'diplomatic' | 'mercantile';
 export interface Resources {
     gold: number;
@@ -14,6 +15,7 @@ export interface Territory {
     armies: number;
     resources: Resources;
     adjacentTo: string[];
+    buildings: BuildingType[];
 }
 export interface Faction {
     id: string;

package/dist/index.js

@@ -7,6 +7,7 @@ import { newGame, saveGame, loadGame, listSaves, checkWinCondition } from './sta
 import { processTurnResources } from './engine/resource-calculator.js';
 import { resolveCombat } from './engine/combat-resolver.js';
 import { recruitArmy, findArmyInTerritory, applyCasualties, ensureArmyRecord } from './engine/army-manager.js';
+import { buildStructure, BUILDINGS, getRecruitGoldCost } from './engine/building-manager.js';
 import { printLine, printSeparator, printStatus, printHelp, printMap, printTerritoryInfo, ICONS } from './ui/display-helpers.js';
 import { runAiTurns } from './engine/ai-turn-processor.js';
 const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -70,10 +71,16 @@ async function processCommand(input, state) {
                 printLine(chalk.red(`No army in ${from.name}.`));
                 break;
             }
-            const toMove = unitCount > 0 ? Math.min(unitCount, army.units) : army.units;
+            const MIN_GARRISON = 2;
+            const movable = army.units - MIN_GARRISON;
+            if (movable <= 0) {
+                printLine(chalk.red(`Cannot move — need at least ${MIN_GARRISON} garrison in ${from.name}. (${army.units} units, ${movable} movable)`));
+                break;
+            }
+            const toMove = unitCount > 0 ? Math.min(unitCount, movable) : movable;
             const remaining = army.units - toMove;
             if (toMove === 0) {
-                printLine(chalk.red('Must move at least 1 unit.'));
+                printLine(chalk.red(`No movable units. ${army.units} in ${from.name}, ${MIN_GARRISON} must garrison.`));
                 break;
             }
             // Update source
@@ -124,7 +131,8 @@ async function processCommand(input, state) {
                 printLine(chalk.red(err));
                 break;
             }
-            printLine(chalk.green(`${ICONS.shield} Recruited ${n} units in ${terr.name}. (${ICONS.gold}-${n * 3} ${ICONS.food}-${n * 2})`));
+            const goldCost = getRecruitGoldCost(terr);
+            printLine(chalk.green(`${ICONS.shield} Recruited ${n} units in ${terr.name}. (${ICONS.gold}-${n * goldCost} ${ICONS.food}-${n * 2})`));
             break;
         }
         case 'attack': {
@@ -157,7 +165,7 @@ async function processCommand(input, state) {
                 break;
             }
             printLine(chalk.yellow(`\n  ${ICONS.fire} Battle: ${from.name} (${attackerArmy.units}) → ${to.name} (${to.armies})`));
-            const result = resolveCombat(attackerArmy.units, attackerArmy.morale, to.armies, 80, to.type);
+            const result = resolveCombat(attackerArmy.units, attackerArmy.morale, to.armies, 80, to.type, to);
             result.log.forEach((l) => printLine(`  ${l}`));
             applyCasualties(attackerArmy, result.attackerCasualties, player, state.armies, from);
             if (result.captured) {
@@ -179,6 +187,35 @@ async function processCommand(input, state) {
             }
             break;
         }
+        case 'build': {
+            // build <territory> <type>
+            if (args.length < 2) {
+                printLine('Usage: build <territory> <walls|barracks|market>');
+                printLine('');
+                for (const b of Object.values(BUILDINGS)) {
+                    const costParts = Object.entries(b.cost).filter(([, v]) => v > 0).map(([k, v]) => `${v}${k[0]}`);
+                    printLine(`  ${b.icon} ${b.label.padEnd(10)} ${costParts.join(' ').padEnd(12)} ${b.description}`);
+                }
+                printLine('');
+                break;
+            }
+            const buildType = args[args.length - 1].toLowerCase();
+            const buildTerrName = args.slice(0, -1).join(' ');
+            const buildTerr = findTerritory(state, buildTerrName);
+            if (!buildTerr) {
+                printLine(chalk.red(`Territory "${buildTerrName}" not found.`));
+                break;
+            }
+            const buildErr = buildStructure(player, buildTerr, buildType);
+            if (buildErr) {
+                printLine(chalk.red(buildErr));
+                break;
+            }
+            const def = BUILDINGS[buildType];
+            const costStr = Object.entries(def.cost).filter(([, v]) => v > 0).map(([k, v]) => `${ICONS[k] ?? k}-${v}`).join(' ');
+            printLine(chalk.green(`${def.icon} Built ${def.label} in ${buildTerr.name}! (${costStr})`));
+            break;
+        }
         case 'save': {
             saveGame(state, args[0] ?? 'autosave');
             printLine(chalk.green(`Game saved to "${args[0] ?? 'autosave'}".`));
@@ -275,6 +312,16 @@ async function runGameLoop(state) {
             state.isOver = true;
             state.winner = winner;
             printLine(chalk.bold.yellow(`\n  ${ICONS.crown} ${state.factions.get(winner).name} has conquered the world! Game over.\n`));
+            printLine('  1. Play Again');
+            printLine('  2. Exit\n');
+            const choice = await ask('  Choose: ');
+            if (choice.trim() === '1') {
+                return mainMenu();
+            }
+            else {
+                rl.close();
+                process.exit(0);
+            }
         }
     }
 }
@@ -285,8 +332,17 @@ async function mainMenu() {
     printLine(chalk.bold.cyan('  ╚════════════════════════════╝\n'));
     printLine('  1. New Game');
     printLine('  2. Load Game');
-    printLine('  3. Quit\n');
+    printLine('  3. Tutorial');
+    printLine('  4. Quit\n');
     const choice = await ask('  Choose: ');
+    if (choice.trim() === '3') {
+        await showTutorial();
+        return mainMenu();
+    }
+    if (choice.trim() === '4') {
+        rl.close();
+        process.exit(0);
+    }
     if (choice.trim() === '1') {
         printLine('\nChoose your faction:');
         printLine('  1. 🔴 Iron Legion (aggressive)');
@@ -317,4 +373,101 @@ async function mainMenu() {
         process.exit(0);
     }
 }
+// ─── Tutorial ────────────────────────────────────────────────────────────────
+async function showTutorial() {
+    const pages = [
+        // Page 1: Overview
+        [
+            chalk.bold.cyan('\n  ═══ HOW TO PLAY ═══\n'),
+            chalk.bold('  🎯 Goal'),
+            '  Conquer all 8 territories on the map to win.',
+            '  You start with 2 territories. Enemy factions hold the rest.',
+            '',
+            chalk.bold('  ⏳ Turns'),
+            '  Each turn you get 3 actions. Actions are:',
+            '    • recruit — train new soldiers',
+            '    • move    — march armies between territories',
+            '    • attack  — invade enemy territory',
+            '    • build   — construct buildings',
+            '',
+            '  Free commands (unlimited): look, info, status, help, save',
+            '  Type "next" to end your turn early.',
+        ],
+        // Page 2: Economy & Resources
+        [
+            chalk.bold.cyan('\n  ═══ RESOURCES ═══\n'),
+            chalk.bold('  💰 Gold  — recruit armies (3g each, 2g with barracks)'),
+            chalk.bold('  🍖 Food  — recruit armies (2f each) + army upkeep (1f/unit/turn)'),
+            chalk.bold('  🪵 Wood  — build structures'),
+            chalk.bold('  🪨 Stone — build structures'),
+            '',
+            '  Each territory produces resources every turn.',
+            '  More territories = more income = bigger army.',
+            '',
+            chalk.bold('  💡 Tip: ') + 'Use "info <territory>" to see resource output.',
+        ],
+        // Page 3: Combat
+        [
+            chalk.bold.cyan('\n  ═══ COMBAT ═══\n'),
+            '  Attack from YOUR territory into an ADJACENT enemy territory.',
+            '  Example: attack crossroads greenwood',
+            '',
+            chalk.bold('  Terrain defense bonuses:'),
+            '    🌾 Plains   — x1.0 (no bonus)',
+            '    🌲 Forest   — x1.2',
+            '    🏰 City     — x1.3',
+            '    ⛰️  Mountain — x1.5',
+            '',
+            chalk.bold('  Outcomes depend on power ratio:'),
+            '    2:1+ → Decisive victory (low losses)',
+            '    1.2:1 → Victory (moderate losses)',
+            '    ~1:1 → Pyrrhic (heavy losses both sides)',
+            '    Below → Defeat (you lose units, they don\'t)',
+            '',
+            chalk.bold('  💡 Tip: ') + 'Outnumber defenders 2:1 for clean wins.',
+        ],
+        // Page 4: Buildings
+        [
+            chalk.bold.cyan('\n  ═══ BUILDINGS ═══\n'),
+            '  Build structures to strengthen your territories.',
+            '  Command: build <territory> <type>',
+            '',
+            '  🧱 Walls      10🪵 15🪨   +0.3 defense bonus',
+            '  🏛️ Barracks    8🪵  5🪨   recruit costs 2💰 instead of 3💰',
+            '  🏪 Market     10💰  5🪵 3🪨  +2💰 income per turn',
+            '',
+            '  Each territory can have all 3 buildings.',
+            '  Buildings show as icons on the map next to your territory.',
+            '',
+            chalk.bold('  💡 Tip: ') + 'Build markets early for economy, walls on borders.',
+        ],
+        // Page 5: Strategy
+        [
+            chalk.bold.cyan('\n  ═══ STRATEGY TIPS ═══\n'),
+            '  1. Don\'t rush — build your economy first (markets!)',
+            '  2. Recruit in bulk, then attack with overwhelming force',
+            '  3. Mountains are hard to capture — bring 2x defenders',
+            '  4. Each territory keeps a garrison of 2 when moving',
+            '  5. Watch enemy actions at end of turn — defend borders',
+            '  6. Build barracks in your main recruiting territory',
+            '  7. Build walls on border territories facing enemies',
+            '',
+            chalk.bold('  🏆 Factions:'),
+            '  🔴 Iron Legion  — starts strong, aggressive AI',
+            '  🟢 Green Pact   — high food/wood, defensive AI',
+            '  🟡 Sand Empire  — rich in gold, balanced AI',
+            '  🟣 Void Covenant — mountain fortress, cautious AI',
+        ],
+    ];
+    for (let i = 0; i < pages.length; i++) {
+        pages[i].forEach((line) => printLine(line));
+        printLine('');
+        if (i < pages.length - 1) {
+            await ask(chalk.gray(`  [Page ${i + 1}/${pages.length}] Press Enter for next page...`));
+        }
+        else {
+            await ask(chalk.gray(`  [Page ${pages.length}/${pages.length}] Press Enter to return to menu...`));
+        }
+    }
+}
 mainMenu().catch((err) => { console.error(chalk.red('Fatal:'), err); process.exit(1); });

package/dist/state/game-state-manager.js

@@ -61,6 +61,11 @@ export function toSaveData(state) {
  * Deserialize SaveData back into a live GameState.
  */
 export function fromSaveData(data) {
+    // Backfill buildings for old saves
+    for (const t of Object.values(data.territories)) {
+        if (!t.buildings)
+            t.buildings = [];
+    }
     return {
         turn: data.turn,
         territories: new Map(Object.entries(data.territories)),

package/dist/ui/display-helpers.js

@@ -1,5 +1,6 @@
 // UI display helpers: icons, status, map, help text
 import chalk from 'chalk';
+import { BUILDINGS } from '../engine/building-manager.js';
 export const ICONS = {
     city: '🏰', forest: '🌲', mountain: '⛰️ ', plains: '🌾',
     gold: '💰', food: '🍖', wood: '🪵', stone: '🪨',
@@ -29,6 +30,7 @@ export function printHelp() {
     printLine('  move <from> <to> [n]        — move n units between territories (all if omitted)');
     printLine('  recruit <territory> <n>     — recruit n units (3💰 + 2🍖 each)');
     printLine('  attack <from> <to>          — attack enemy territory from yours');
+    printLine('  build <territory> <type>    — build walls/barracks/market (🪵🪨)');
     printLine('  next                        — end turn (enemies act after this)');
     printLine('  save [slot]                 — save game');
     printLine('  quit                        — exit game');
@@ -46,7 +48,8 @@ export function printMap(state) {
         const icon = ICONS[t.type] ?? '?';
         const armies = t.armies > 0 ? ` ${ICONS.army} ${t.armies}` : '';
         const yours = t.owner === playerId ? chalk.green(' ★') : '';
-        printLine(`  ${icon} ${colorFn(t.name.padEnd(14))} ${colorFn(ownerName)}${armies}${yours}`);
+        const bldgs = (t.buildings ?? []).map((b) => BUILDINGS[b]?.icon ?? '').join('');
+        printLine(`  ${icon} ${colorFn(t.name.padEnd(14))} ${colorFn(ownerName)}${armies}${yours}${bldgs ? ' ' + bldgs : ''}`);
         const adjNames = t.adjacentTo.map((id) => state.territories.get(id)?.name ?? id).join(', ');
         printLine(chalk.gray(`     ↔ ${adjNames}`));
     }
@@ -67,6 +70,8 @@ export function printTerritoryInfo(state, territoryName) {
     printLine(`  Owner: ${ownerFaction?.name ?? 'Unclaimed'}`);
     printLine(`  ${ICONS.army} Armies: ${t.armies}`);
     printLine(`  Resources/turn: ${ICONS.gold}${t.resources.gold} ${ICONS.food}${t.resources.food} ${ICONS.wood}${t.resources.wood} ${ICONS.stone}${t.resources.stone}`);
+    const bldgs = (t.buildings ?? []).map((b) => `${BUILDINGS[b]?.icon ?? ''} ${BUILDINGS[b]?.label ?? b}`).join(', ');
+    printLine(`  Buildings: ${bldgs || 'none'}`);
     printLine(`  Neighbors:`);
     for (const adjId of t.adjacentTo) {
         const adj = state.territories.get(adjId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "empire-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI strategy RPG with AI game master",
   "type": "module",
   "main": "dist/index.js",

package/src/data/default-world-map.ts

@@ -19,6 +19,7 @@ export const DEFAULT_TERRITORIES: Territory[] = [
     armies: 3,
     resources: { gold: 4, food: 2, wood: 1, stone: 2 },
     adjacentTo: ['iron_hills', 'greenwood'],
+    buildings: [],
   },
   {
     id: 'iron_hills',
@@ -28,6 +29,7 @@ export const DEFAULT_TERRITORIES: Territory[] = [
     armies: 2,
     resources: { gold: 2, food: 1, wood: 0, stone: 4 },
     adjacentTo: ['northkeep', 'crossroads'],
+    buildings: [],
   },
   {
     id: 'greenwood',
@@ -37,6 +39,7 @@ export const DEFAULT_TERRITORIES: Territory[] = [
     armies: 2,
     resources: { gold: 1, food: 3, wood: 4, stone: 0 },
     adjacentTo: ['northkeep', 'crossroads', 'silver_bay'],
+    buildings: [],
   },
   {
     id: 'crossroads',
@@ -46,6 +49,7 @@ export const DEFAULT_TERRITORIES: Territory[] = [
     armies: 0,
     resources: { gold: 2, food: 2, wood: 1, stone: 1 },
     adjacentTo: ['iron_hills', 'greenwood', 'desert_gate', 'stonehaven'],
+    buildings: [],
   },
   {
     id: 'desert_gate',
@@ -55,6 +59,7 @@ export const DEFAULT_TERRITORIES: Territory[] = [
     armies: 2,
     resources: { gold: 3, food: 1, wood: 0, stone: 2 },
     adjacentTo: ['crossroads'],
+    buildings: [],
   },
   {
     id: 'silver_bay',
@@ -64,6 +69,7 @@ export const DEFAULT_TERRITORIES: Territory[] = [
     armies: 3,
     resources: { gold: 5, food: 2, wood: 1, stone: 1 },
     adjacentTo: ['greenwood', 'stonehaven'],
+    buildings: [],
   },
   {
     id: 'stonehaven',
@@ -73,6 +79,7 @@ export const DEFAULT_TERRITORIES: Territory[] = [
     armies: 2,
     resources: { gold: 2, food: 1, wood: 0, stone: 5 },
     adjacentTo: ['crossroads', 'silver_bay', 'dragon_peak'],
+    buildings: [],
   },
   {
     id: 'dragon_peak',
@@ -82,6 +89,7 @@ export const DEFAULT_TERRITORIES: Territory[] = [
     armies: 4,
     resources: { gold: 1, food: 0, wood: 0, stone: 6 },
     adjacentTo: ['stonehaven'],
+    buildings: [],
   },
 ];
 

package/src/engine/ai-turn-processor.ts

@@ -46,7 +46,7 @@ export function runAiTurns(state: GameState): string[] {
         if (attackerUnits < 2) continue;
         if (attackerUnits < defenderUnits && faction.personality !== 'aggressive') continue;
 
-        const result = resolveCombat(attackerUnits, 80, defenderUnits, 80, adj.type);
+        const result = resolveCombat(attackerUnits, 80, defenderUnits, 80, adj.type, adj);
         log.push(`${faction.name} attacks ${adj.name} from ${territory.name}!`);
 
         const attackerArmy = findArmyInTerritory(faction.id, territoryId, state.armies);

package/src/engine/army-manager.ts

@@ -2,8 +2,9 @@
 
 import type { Army, Faction, Territory, GameState } from '../game-types.js';
 import { canAfford, deductResources } from './resource-calculator.js';
+import { getRecruitGoldCost } from './building-manager.js';
 
-const RECRUIT_COST_PER_UNIT = { gold: 3, food: 2, wood: 0, stone: 0 };
+const RECRUIT_FOOD_PER_UNIT = 2;
 const DEFAULT_MORALE = 80;
 
 let armyIdCounter = 1;
@@ -29,9 +30,10 @@ export function recruitArmy(
     return 'Must recruit at least 1 unit.';
   }
 
+  const goldPerUnit = getRecruitGoldCost(territory);
   const totalCost = {
-    gold: RECRUIT_COST_PER_UNIT.gold * units,
-    food: RECRUIT_COST_PER_UNIT.food * units,
+    gold: goldPerUnit * units,
+    food: RECRUIT_FOOD_PER_UNIT * units,
   };
 
   if (!canAfford(faction, totalCost)) {

package/src/engine/building-manager.ts

@@ -0,0 +1,72 @@
+// Building construction logic: walls (defense), barracks (cheaper recruits), market (gold income)
+
+import type { BuildingType, Faction, Territory, Resources } from '../game-types.js';
+
+export interface BuildingDef {
+  type: BuildingType;
+  label: string;
+  icon: string;
+  cost: Partial<Resources>;
+  description: string;
+}
+
+export const BUILDINGS: Record<BuildingType, BuildingDef> = {
+  walls:    { type: 'walls',    label: 'Walls',    icon: '🧱', cost: { wood: 10, stone: 15 }, description: '+0.3 defense bonus' },
+  barracks: { type: 'barracks', label: 'Barracks', icon: '🏛️', cost: { wood: 8, stone: 5 },   description: 'recruit costs 2g instead of 3g' },
+  market:   { type: 'market',   label: 'Market',   icon: '🏪', cost: { gold: 10, wood: 5, stone: 3 }, description: '+2 gold income/turn' },
+};
+
+/**
+ * Build a structure in a territory. Returns error message or null on success.
+ */
+export function buildStructure(
+  faction: Faction,
+  territory: Territory,
+  buildingType: BuildingType
+): string | null {
+  if (territory.owner !== faction.id) {
+    return `You don't own ${territory.name}.`;
+  }
+
+  const def = BUILDINGS[buildingType];
+  if (!def) return `Unknown building: ${buildingType}. Available: walls, barracks, market`;
+
+  if (territory.buildings.includes(buildingType)) {
+    return `${territory.name} already has ${def.label}.`;
+  }
+
+  // Check cost
+  const cost = def.cost;
+  if ((cost.gold ?? 0) > faction.gold) return `Not enough gold. Need ${cost.gold}, have ${faction.gold}.`;
+  if ((cost.wood ?? 0) > faction.wood) return `Not enough wood. Need ${cost.wood}, have ${faction.wood}.`;
+  if ((cost.stone ?? 0) > faction.stone) return `Not enough stone. Need ${cost.stone}, have ${faction.stone}.`;
+
+  // Deduct resources
+  faction.gold -= cost.gold ?? 0;
+  faction.wood -= cost.wood ?? 0;
+  faction.stone -= cost.stone ?? 0;
+
+  territory.buildings.push(buildingType);
+  return null;
+}
+
+/**
+ * Get defense bonus from buildings in a territory (added to terrain bonus).
+ */
+export function getBuildingDefenseBonus(territory: Territory): number {
+  return territory.buildings.includes('walls') ? 0.3 : 0;
+}
+
+/**
+ * Get recruit cost discount from barracks.
+ */
+export function getRecruitGoldCost(territory: Territory): number {
+  return territory.buildings.includes('barracks') ? 2 : 3;
+}
+
+/**
+ * Get bonus gold income from market.
+ */
+export function getMarketGoldBonus(territory: Territory): number {
+  return territory.buildings.includes('market') ? 2 : 0;
+}

package/src/engine/combat-resolver.ts

@@ -1,6 +1,7 @@
 // Combat resolution engine: calculates battle outcomes based on units, morale, terrain
 
-import type { CombatResult, TerritoryType } from '../game-types.js';
+import type { CombatResult, TerritoryType, Territory } from '../game-types.js';
+import { getBuildingDefenseBonus } from './building-manager.js';
 
 // Terrain defense bonuses (multiplier on defender power)
 const TERRAIN_BONUS: Record<TerritoryType, number> = {
@@ -19,16 +20,20 @@ export function resolveCombat(
   attackerMorale: number,
   defenderUnits: number,
   defenderMorale: number,
-  terrain: TerritoryType
+  terrain: TerritoryType,
+  defenderTerritory?: Territory
 ): CombatResult {
   const log: string[] = [];
 
   const terrainBonus = TERRAIN_BONUS[terrain];
+  const wallBonus = defenderTerritory ? getBuildingDefenseBonus(defenderTerritory) : 0;
+  const totalDefBonus = terrainBonus + wallBonus;
   const attackPower = attackerUnits * (attackerMorale / 100);
-  const defensePower = defenderUnits * (defenderMorale / 100) * terrainBonus;
+  const defensePower = defenderUnits * (defenderMorale / 100) * totalDefBonus;
 
   log.push(`Attack power: ${attackPower.toFixed(1)} vs Defense power: ${defensePower.toFixed(1)}`);
   log.push(`Terrain (${terrain}) gives defender x${terrainBonus} bonus`);
+  if (wallBonus > 0) log.push(`Walls give defender +${wallBonus} bonus`);
 
   const ratio = attackPower / (defensePower || 1);
 

package/src/engine/resource-calculator.ts

@@ -1,6 +1,7 @@
 // Resource collection and upkeep calculations for each faction per turn
 
 import type { Faction, Territory, Resources } from '../game-types.js';
+import { getMarketGoldBonus } from './building-manager.js';
 
 const ARMY_FOOD_UPKEEP = 1; // food per army unit per turn
 const ARMY_GOLD_UPKEEP = 0; // gold per army unit (free for now)
@@ -18,7 +19,7 @@ export function collectResources(
     const territory = territories.get(territoryId);
     if (!territory) continue;
 
-    income.gold += territory.resources.gold;
+    income.gold += territory.resources.gold + getMarketGoldBonus(territory);
     income.food += territory.resources.food;
     income.wood += territory.resources.wood;
     income.stone += territory.resources.stone;

package/src/game-types.ts

@@ -2,6 +2,8 @@
 
 export type TerritoryType = 'plains' | 'forest' | 'mountain' | 'city';
 
+export type BuildingType = 'walls' | 'barracks' | 'market';
+
 export type FactionPersonality = 'aggressive' | 'defensive' | 'diplomatic' | 'mercantile';
 
 export interface Resources {
@@ -19,6 +21,7 @@ export interface Territory {
   armies: number;
   resources: Resources; // base income per turn
   adjacentTo: string[]; // territory ids
+  buildings: BuildingType[]; // built structures
 }
 
 export interface Faction {

package/src/index.ts

@@ -9,6 +9,8 @@ import { newGame, saveGame, loadGame, listSaves, checkWinCondition } from './sta
 import { processTurnResources } from './engine/resource-calculator.js';
 import { resolveCombat } from './engine/combat-resolver.js';
 import { recruitArmy, findArmyInTerritory, applyCasualties, getUnitsInTerritory, ensureArmyRecord } from './engine/army-manager.js';
+import { buildStructure, BUILDINGS, getRecruitGoldCost } from './engine/building-manager.js';
+import type { BuildingType } from './game-types.js';
 import { printLine, printSeparator, printStatus, printHelp, printMap, printTerritoryInfo, ICONS } from './ui/display-helpers.js';
 import { runAiTurns } from './engine/ai-turn-processor.js';
 
@@ -60,9 +62,12 @@ async function processCommand(input: string, state: GameState): Promise<boolean>
       const army = findArmyInTerritory(player.id, from.id, state.armies);
       if (!army || army.units === 0) { printLine(chalk.red(`No army in ${from.name}.`)); break; }
 
-      const toMove = unitCount > 0 ? Math.min(unitCount, army.units) : army.units;
+      const MIN_GARRISON = 2;
+      const movable = army.units - MIN_GARRISON;
+      if (movable <= 0) { printLine(chalk.red(`Cannot move — need at least ${MIN_GARRISON} garrison in ${from.name}. (${army.units} units, ${movable} movable)`)); break; }
+      const toMove = unitCount > 0 ? Math.min(unitCount, movable) : movable;
       const remaining = army.units - toMove;
-      if (toMove === 0) { printLine(chalk.red('Must move at least 1 unit.')); break; }
+      if (toMove === 0) { printLine(chalk.red(`No movable units. ${army.units} in ${from.name}, ${MIN_GARRISON} must garrison.`)); break; }
 
       // Update source
       if (remaining > 0) { army.units = remaining; from.armies = remaining; }
@@ -91,7 +96,8 @@ async function processCommand(input: string, state: GameState): Promise<boolean>
 
       const err = recruitArmy(player, terr, n, state.armies);
       if (err) { printLine(chalk.red(err)); break; }
-      printLine(chalk.green(`${ICONS.shield} Recruited ${n} units in ${terr.name}. (${ICONS.gold}-${n * 3} ${ICONS.food}-${n * 2})`));
+      const goldCost = getRecruitGoldCost(terr);
+      printLine(chalk.green(`${ICONS.shield} Recruited ${n} units in ${terr.name}. (${ICONS.gold}-${n * goldCost} ${ICONS.food}-${n * 2})`));
       break;
     }
 
@@ -109,7 +115,7 @@ async function processCommand(input: string, state: GameState): Promise<boolean>
       if (!attackerArmy || attackerArmy.units === 0) { printLine(chalk.red(`No army in ${from.name}.`)); break; }
 
       printLine(chalk.yellow(`\n  ${ICONS.fire} Battle: ${from.name} (${attackerArmy.units}) → ${to.name} (${to.armies})`));
-      const result = resolveCombat(attackerArmy.units, attackerArmy.morale, to.armies, 80, to.type);
+      const result = resolveCombat(attackerArmy.units, attackerArmy.morale, to.armies, 80, to.type, to);
       result.log.forEach((l) => printLine(`  ${l}`));
 
       applyCasualties(attackerArmy, result.attackerCasualties, player, state.armies, from);
@@ -131,6 +137,30 @@ async function processCommand(input: string, state: GameState): Promise<boolean>
       break;
     }
 
+    case 'build': {
+      // build <territory> <type>
+      if (args.length < 2) {
+        printLine('Usage: build <territory> <walls|barracks|market>');
+        printLine('');
+        for (const b of Object.values(BUILDINGS)) {
+          const costParts = Object.entries(b.cost).filter(([, v]) => v > 0).map(([k, v]) => `${v}${k[0]}`);
+          printLine(`  ${b.icon} ${b.label.padEnd(10)} ${costParts.join(' ').padEnd(12)} ${b.description}`);
+        }
+        printLine('');
+        break;
+      }
+      const buildType = args[args.length - 1].toLowerCase() as BuildingType;
+      const buildTerrName = args.slice(0, -1).join(' ');
+      const buildTerr = findTerritory(state, buildTerrName);
+      if (!buildTerr) { printLine(chalk.red(`Territory "${buildTerrName}" not found.`)); break; }
+      const buildErr = buildStructure(player, buildTerr, buildType);
+      if (buildErr) { printLine(chalk.red(buildErr)); break; }
+      const def = BUILDINGS[buildType];
+      const costStr = Object.entries(def.cost).filter(([, v]) => v > 0).map(([k, v]) => `${ICONS[k] ?? k}-${v}`).join(' ');
+      printLine(chalk.green(`${def.icon} Built ${def.label} in ${buildTerr.name}! (${costStr})`));
+      break;
+    }
+
     case 'save': {
       saveGame(state, args[0] ?? 'autosave');
       printLine(chalk.green(`Game saved to "${args[0] ?? 'autosave'}".`));
@@ -226,6 +256,11 @@ async function runGameLoop(state: GameState): Promise<void> {
     if (winner) {
       state.isOver = true; state.winner = winner;
       printLine(chalk.bold.yellow(`\n  ${ICONS.crown} ${state.factions.get(winner)!.name} has conquered the world! Game over.\n`));
+      printLine('  1. Play Again');
+      printLine('  2. Exit\n');
+      const choice = await ask('  Choose: ');
+      if (choice.trim() === '1') { return mainMenu(); }
+      else { rl.close(); process.exit(0); }
     }
   }
 }
@@ -238,9 +273,15 @@ async function mainMenu(): Promise<void> {
   printLine(chalk.bold.cyan('  ╚════════════════════════════╝\n'));
   printLine('  1. New Game');
   printLine('  2. Load Game');
-  printLine('  3. Quit\n');
+  printLine('  3. Tutorial');
+  printLine('  4. Quit\n');
 
   const choice = await ask('  Choose: ');
+  if (choice.trim() === '3') {
+    await showTutorial();
+    return mainMenu();
+  }
+  if (choice.trim() === '4') { rl.close(); process.exit(0); }
   if (choice.trim() === '1') {
     printLine('\nChoose your faction:');
     printLine('  1. 🔴 Iron Legion (aggressive)');
@@ -261,4 +302,104 @@ async function mainMenu(): Promise<void> {
   } else { rl.close(); process.exit(0); }
 }
 
+// ─── Tutorial ────────────────────────────────────────────────────────────────
+
+async function showTutorial(): Promise<void> {
+  const pages = [
+    // Page 1: Overview
+    [
+      chalk.bold.cyan('\n  ═══ HOW TO PLAY ═══\n'),
+      chalk.bold('  🎯 Goal'),
+      '  Conquer all 8 territories on the map to win.',
+      '  You start with 2 territories. Enemy factions hold the rest.',
+      '',
+      chalk.bold('  ⏳ Turns'),
+      '  Each turn you get 3 actions. Actions are:',
+      '    • recruit — train new soldiers',
+      '    • move    — march armies between territories',
+      '    • attack  — invade enemy territory',
+      '    • build   — construct buildings',
+      '',
+      '  Free commands (unlimited): look, info, status, help, save',
+      '  Type "next" to end your turn early.',
+    ],
+    // Page 2: Economy & Resources
+    [
+      chalk.bold.cyan('\n  ═══ RESOURCES ═══\n'),
+      chalk.bold('  💰 Gold  — recruit armies (3g each, 2g with barracks)'),
+      chalk.bold('  🍖 Food  — recruit armies (2f each) + army upkeep (1f/unit/turn)'),
+      chalk.bold('  🪵 Wood  — build structures'),
+      chalk.bold('  🪨 Stone — build structures'),
+      '',
+      '  Each territory produces resources every turn.',
+      '  More territories = more income = bigger army.',
+      '',
+      chalk.bold('  💡 Tip: ') + 'Use "info <territory>" to see resource output.',
+    ],
+    // Page 3: Combat
+    [
+      chalk.bold.cyan('\n  ═══ COMBAT ═══\n'),
+      '  Attack from YOUR territory into an ADJACENT enemy territory.',
+      '  Example: attack crossroads greenwood',
+      '',
+      chalk.bold('  Terrain defense bonuses:'),
+      '    🌾 Plains   — x1.0 (no bonus)',
+      '    🌲 Forest   — x1.2',
+      '    🏰 City     — x1.3',
+      '    ⛰️  Mountain — x1.5',
+      '',
+      chalk.bold('  Outcomes depend on power ratio:'),
+      '    2:1+ → Decisive victory (low losses)',
+      '    1.2:1 → Victory (moderate losses)',
+      '    ~1:1 → Pyrrhic (heavy losses both sides)',
+      '    Below → Defeat (you lose units, they don\'t)',
+      '',
+      chalk.bold('  💡 Tip: ') + 'Outnumber defenders 2:1 for clean wins.',
+    ],
+    // Page 4: Buildings
+    [
+      chalk.bold.cyan('\n  ═══ BUILDINGS ═══\n'),
+      '  Build structures to strengthen your territories.',
+      '  Command: build <territory> <type>',
+      '',
+      '  🧱 Walls      10🪵 15🪨   +0.3 defense bonus',
+      '  🏛️ Barracks    8🪵  5🪨   recruit costs 2💰 instead of 3💰',
+      '  🏪 Market     10💰  5🪵 3🪨  +2💰 income per turn',
+      '',
+      '  Each territory can have all 3 buildings.',
+      '  Buildings show as icons on the map next to your territory.',
+      '',
+      chalk.bold('  💡 Tip: ') + 'Build markets early for economy, walls on borders.',
+    ],
+    // Page 5: Strategy
+    [
+      chalk.bold.cyan('\n  ═══ STRATEGY TIPS ═══\n'),
+      '  1. Don\'t rush — build your economy first (markets!)',
+      '  2. Recruit in bulk, then attack with overwhelming force',
+      '  3. Mountains are hard to capture — bring 2x defenders',
+      '  4. Each territory keeps a garrison of 2 when moving',
+      '  5. Watch enemy actions at end of turn — defend borders',
+      '  6. Build barracks in your main recruiting territory',
+      '  7. Build walls on border territories facing enemies',
+      '',
+      chalk.bold('  🏆 Factions:'),
+      '  🔴 Iron Legion  — starts strong, aggressive AI',
+      '  🟢 Green Pact   — high food/wood, defensive AI',
+      '  🟡 Sand Empire  — rich in gold, balanced AI',
+      '  🟣 Void Covenant — mountain fortress, cautious AI',
+    ],
+  ];
+
+  for (let i = 0; i < pages.length; i++) {
+    pages[i].forEach((line) => printLine(line));
+    printLine('');
+    if (i < pages.length - 1) {
+      await ask(chalk.gray(`  [Page ${i + 1}/${pages.length}] Press Enter for next page...`));
+    } else {
+      await ask(chalk.gray(`  [Page ${pages.length}/${pages.length}] Press Enter to return to menu...`));
+    }
+  }
+}
+
+
 mainMenu().catch((err) => { console.error(chalk.red('Fatal:'), err); process.exit(1); });

package/src/state/game-state-manager.ts

@@ -70,6 +70,10 @@ export function toSaveData(state: GameState): SaveData {
  * Deserialize SaveData back into a live GameState.
  */
 export function fromSaveData(data: SaveData): GameState {
+  // Backfill buildings for old saves
+  for (const t of Object.values(data.territories)) {
+    if (!t.buildings) (t as any).buildings = [];
+  }
   return {
     turn: data.turn,
     territories: new Map(Object.entries(data.territories)),

package/src/ui/display-helpers.ts

@@ -2,6 +2,7 @@
 import chalk from 'chalk';
 import type { GameState } from '../game-types.js';
 import { findArmyInTerritory } from '../engine/army-manager.js';
+import { BUILDINGS } from '../engine/building-manager.js';
 
 export const ICONS: Record<string, string> = {
   city: '🏰', forest: '🌲', mountain: '⛰️ ', plains: '🌾',
@@ -36,6 +37,7 @@ export function printHelp(): void {
   printLine('  move <from> <to> [n]        — move n units between territories (all if omitted)');
   printLine('  recruit <territory> <n>     — recruit n units (3💰 + 2🍖 each)');
   printLine('  attack <from> <to>          — attack enemy territory from yours');
+  printLine('  build <territory> <type>    — build walls/barracks/market (🪵🪨)');
   printLine('  next                        — end turn (enemies act after this)');
   printLine('  save [slot]                 — save game');
   printLine('  quit                        — exit game');
@@ -54,7 +56,8 @@ export function printMap(state: GameState): void {
     const icon = ICONS[t.type] ?? '?';
     const armies = t.armies > 0 ? ` ${ICONS.army} ${t.armies}` : '';
     const yours = t.owner === playerId ? chalk.green(' ★') : '';
-    printLine(`  ${icon} ${colorFn(t.name.padEnd(14))} ${colorFn(ownerName)}${armies}${yours}`);
+    const bldgs = (t.buildings ?? []).map((b) => BUILDINGS[b]?.icon ?? '').join('');
+    printLine(`  ${icon} ${colorFn(t.name.padEnd(14))} ${colorFn(ownerName)}${armies}${yours}${bldgs ? ' ' + bldgs : ''}`);
     const adjNames = t.adjacentTo.map((id) => state.territories.get(id)?.name ?? id).join(', ');
     printLine(chalk.gray(`     ↔ ${adjNames}`));
   }
@@ -77,6 +80,8 @@ export function printTerritoryInfo(state: GameState, territoryName: string): voi
   printLine(`  Owner: ${ownerFaction?.name ?? 'Unclaimed'}`);
   printLine(`  ${ICONS.army} Armies: ${t.armies}`);
   printLine(`  Resources/turn: ${ICONS.gold}${t.resources.gold} ${ICONS.food}${t.resources.food} ${ICONS.wood}${t.resources.wood} ${ICONS.stone}${t.resources.stone}`);
+  const bldgs = (t.buildings ?? []).map((b) => `${BUILDINGS[b]?.icon ?? ''} ${BUILDINGS[b]?.label ?? b}`).join(', ');
+  printLine(`  Buildings: ${bldgs || 'none'}`);
   printLine(`  Neighbors:`);
   for (const adjId of t.adjacentTo) {
     const adj = state.territories.get(adjId)!;

package/assets/gameplay-output.txt

@@ -1,117 +0,0 @@
-
-  ╔════════════════════════════╗
-  ║  ⚔️  E M P I R E  CLI  👑  ║
-  ╚════════════════════════════╝
-
-  1. New Game
-  2. Load Game
-  3. Quit
-
-  Choose: 
-Choose your faction:
-  1. 🔴 Iron Legion (aggressive)
-  2. 🟢 Green Pact (defensive)
-  3. 🟡 Sand Empire (mercantile)
-  4. 🟣 Void Covenant (diplomatic)
-
-  Choose: 
-  👑 Welcome to Empire CLI ⚔️ 
-
-
-  Commands:
-  look                        — show world map
-  info <territory>            — show territory details
-  status                      — show your resources
-  move <from> <to> [n]        — move n units between territories (all if omitted)
-  recruit <territory> <n>     — recruit n units (3💰 + 2🍖 each)
-  attack <from> <to>          — attack enemy territory from yours
-  next                        — end turn (enemies act after this)
-  save [slot]                 — save game
-  quit                        — exit game
-  help                        — show this help
-
-────────────────────────────────────────────────────────────
-  👑 Iron Legion  —  Turn 1
-  💰 20  🍖 10  🪵 5  🪨 15
-  ⚔️  Armies: 5  |  🚩 Territories: 2/8
-────────────────────────────────────────────────────────────
-  Turn 1 [3/3 actions] > 
-  World Map:
-
-  🏰 Northkeep      Iron Legion ⚔️  3 ★
-     ↔ Iron Hills, Greenwood
-  ⛰️  Iron Hills     Iron Legion ⚔️  2 ★
-     ↔ Northkeep, Crossroads
-  🌲 Greenwood      Green Pact ⚔️  2
-     ↔ Northkeep, Crossroads, Silver Bay
-  🌾 Crossroads     Unclaimed
-     ↔ Iron Hills, Greenwood, Desert Gate, Stonehaven
-  🌾 Desert Gate    Sand Empire ⚔️  2
-     ↔ Crossroads
-  🏰 Silver Bay     Green Pact ⚔️  3
-     ↔ Greenwood, Stonehaven
-  ⛰️  Stonehaven     Sand Empire ⚔️  2
-     ↔ Crossroads, Silver Bay, Dragon Peak
-  ⛰️  Dragon Peak    Void Covenant ⚔️  4
-     ↔ Stonehaven
-
-  Turn 1 [3/3 actions] > 
-  🏰 Northkeep (city)
-  Owner: Iron Legion
-  ⚔️  Armies: 3
-  Resources/turn: 💰4 🍖2 🪵1 🪨2
-  Neighbors:
-    → ⛰️  Iron Hills — Iron Legion ★
-    → 🌲 Greenwood — Green Pact ⚔️ 2
-
-  Turn 1 [3/3 actions] > 🛡️  Recruited 2 units in Northkeep. (💰-6 🍖-4)
-  Turn 1 [2/3 actions] > ⚔️  Moved 3 units: Northkeep → Iron Hills (2 garrison Northkeep)
-  Turn 1 [1/3 actions] > 
-  🔥 Battle: Iron Hills (5) → Crossroads (0)
-  Attack power: 4.0 vs Defense power: 0.0
-  Terrain (plains) gives defender x1 bonus
-  Decisive victory! The defenders are routed!
-  Attacker losses: 0 units
-  Defender losses: 0 units
-
-  🚩 You captured Crossroads!
-
-  ⏰ No actions remaining — turn ends automatically.
-
-────────────────────────────────────────────────────────────
-  --- End of Turn 1 ---
-
-  Iron Legion collected: +8g +5f +2w +7s
-
-  🔥 Enemy Actions:
-  Green Pact recruited 3 units in Greenwood
-  Green Pact attacks Northkeep from Greenwood!
-    → Green Pact captured Northkeep! 🔥
-
-────────────────────────────────────────────────────────────
-────────────────────────────────────────────────────────────
-  👑 Iron Legion  —  Turn 2
-  💰 22  🍖 4  🪵 7  🪨 22
-  ⚔️  Armies: 6  |  🚩 Territories: 2/8
-────────────────────────────────────────────────────────────
-  Turn 2 [3/3 actions] > 
-  World Map:
-
-  🏰 Northkeep      Green Pact ⚔️  4
-     ↔ Iron Hills, Greenwood
-  ⛰️  Iron Hills     Iron Legion ⚔️  5 ★
-     ↔ Northkeep, Crossroads
-  🌲 Greenwood      Green Pact ⚔️  4
-     ↔ Northkeep, Crossroads, Silver Bay
-  🌾 Crossroads     Iron Legion ⚔️  5 ★
-     ↔ Iron Hills, Greenwood, Desert Gate, Stonehaven
-  🌾 Desert Gate    Sand Empire ⚔️  2
-     ↔ Crossroads
-  🏰 Silver Bay     Green Pact ⚔️  3
-     ↔ Greenwood, Stonehaven
-  ⛰️  Stonehaven     Sand Empire ⚔️  2
-     ↔ Crossroads, Silver Bay, Dragon Peak
-  ⛰️  Dragon Peak    Void Covenant ⚔️  4
-     ↔ Stonehaven
-
-  Turn 2 [3/3 actions] > Farewell, Emperor.