AI-GameFriend Manual

• Try basic chess where configured with the model used for advice. Treat commentary as advice, not as certain or authoritative.
• 2-minute personality profile that compares your decision style to four AI baselines (Claude, GPT, Grok, Gemini). Web flow, no install.
• Strategic advisor for six grand-strategy games — describe your situation in text, get three to five turn recommendations with reasoning. You apply moves manually in your own copy of the game. See AI Advisor.
• Decision Duel — write down your intended move first, then compare it against an AI recommendation with safe / aggressive alternatives. See Decision Duel.
• Use experimental comparison surfaces only where configured. Other Arena games stay gated until verified.
• Try gated Slay the Spire Watch through the desktop mod bridge when the bridge and model configuration are ready. Requires CommunicationMod and setup; see STS Watch.

Anything beyond those five claims - AI control of your own strategy game, save-file integration, real-time campaign analysis, or full-game STS/Dominions 6 championships - is not part of the v0.9.9 basic release-candidate scope. The What's Coming section lists what is queued.

What's on the page

Four cards, each leading into a different starting path:

• Civ VI Strategy Brief — describe your current Civ VI position and get a structured second opinion. The most polished starting path.
• Decision Duel — write down what you would do first, then compare against an AI recommendation. See Decision Duel below.
• Sample Scenarios — three prepared situations you can use if you don't have a live game ready. See the next subsection.
• Experimental labs — Slay the Spire and Dominions 6 experiments, clearly labelled as experimental. Use these only if you're comfortable that the underlying flow may be rougher.

Sample scenarios

Sample scenarios let you try the flow before using your own game. Three are included:

• Civ VI midgame war/economy dilemma — you're behind in science, ahead in military, and a neighbouring civ is massing on your border. Convert the lead into a war or stabilise?
• Slay the Spire Act 2 risk/scaling dilemma — strong late scaling, weak block density, a greedy power on offer. Greed or survive?
• Dominions 6 expansion / bless / scales dilemma — choose the right early-game posture for a specific Pretender setup.

Each sample carries a structured prompt so the AI's response comes back in a comparable shape: diagnosis, options, risk, plan, alternatives. Selecting a sample drops you into either the Strategy Brief or Decision Duel page with the context prefilled.

2.1 Install (Windows)

1. 1Download the installer from /downloads/AI-GameFriend_0.9.9_x64-setup.exe (also reachable from /ai-gamefriend/download).
2. 2Run the .exe. Windows SmartScreen will warn — click More info → Run anyway. The installer is unsigned NSIS; we publish the SHA-256 on the download page so you can verify before running.
3. 3On first launch the app opens a 3-step wizard: pick a provider, paste an API key, and pick your first game. You can skip and add the key later in Settings.

2.2 API Keys (BYOK)

AI-GameFriend uses your AI provider account directly. You paste a key, the app stores it in the Windows credential keychain (never on our servers), and every move is sent straight from your machine to your provider. You pay your provider for tokens; we don't sit between you and the bill.

• Claude (Anthropic) — console.anthropic.com. Recommended starter for chess + advisors.
• GPT (OpenAI) — platform.openai.com.
• Grok (xAI) — x.ai/api.
• Gemini (Google) — aistudio.google.com. Use AI Studio (not Google Cloud) for the free tier.

Paste each key in Settings → API Keys and click Test. A green check means it works. Once you have at least two valid keys, a Default provider dropdown appears so you can choose which one pre-selects on new matches.

2.3 Your First Match

Start with chess — it's the most polished flow today and exercises the whole pipeline (board renderer, AI reasoning, cost meter, match history) end-to-end.

1. 1Open Play from the top nav.
2. 2Click the chess card. The setup screen pre-selects chess; pick a provider, model, and personality (e.g. The Strategist or The Berserker).
3. 3Click Start match. The chess board appears; the AI takes its first move within ten seconds and posts a short reasoning note. You play your moves on the board; the AI responds.

Chess — full game

The flagship Play-vs-AI flow. Real chess.js engine, full legal rule enforcement, the AI selects moves with extended thinking and posts a short reasoning note per move. Cost meter is live during the match.

Tabletop classics — chat-based

Risk, Settlers of Catan, Go, Checkers, Battleship, Connect Four, and Tic-Tac-Toe ship as freeform chat. There is no board renderer and no rule enforcement. You describe the current board state in plain English in chat; the AI replies with a move suggestion or a short suggested play. The advice is only as good as how well you describe the state, so these are best for casual or teaching use, not tournament play.

Slay the Spire — setup-required desktop mod flow

Slay the Spire isn't played from the Play hub like the others. It runs through a separate desktop mod bridge against your local Steam copy of STS, while you watch. See STS Watch for the setup and run procedure.

What this is — and what it isn't

What this is: a structured second opinion on your turn. You write a paragraph or two about your current position; the AI returns three to five recommendations, each with reasoning and a confidence score. You approve, reject, or modify each card before you decide what to do in your game.

What this is NOT: a system that drives your strategy game. AI-GameFriend doesn't ingest game-state files, doesn't watch your screen, and doesn't execute moves inside your game. That class of "AI runs the campaign for you" framing belongs to a different product. Direct game-state bridges remain gated unless each bridge is explicitly marked ready.

The eight-step loop

1. 1Open the advisor for your game from Play → AI Advisor.
2. 2Alt-tab to your strategy game. Look at your current turn — your nation, year, threats, opportunities, the decisions you're weighing.
3. 3Alt-tab back to AI-GameFriend. Type a short description of what you observed: faction, year, three or four salient facts.
4. 4Click Get turn plan. The AI returns three to five recommendation cards.
5. 5Read the reasoning and confidence score on each card.
6. 6Approve, reject, or modify each card.
7. 7Alt-tab back to your game. Apply the moves you approved.
8. 8Repeat next turn.

Six advisors

• Civilization VI — district adjacency, wonder timing, victory pathing.
• Crusader Kings III — dynasty management, schemes, marriages.
• Europa Universalis V — diplomacy, trade, war planning.
• Hearts of Iron IV — production priorities, theatre planning.
• Total War: Warhammer III — campaign and battle advice.
• Dominions 6 — Pretender design, research paths, army composition.

Sample-scenario prefill (added in v0.9.8)

From Start Here, the Civ VI sample scenario lands you on this advisor with the situation prefilled — useful as a first try before pasting your own game state.

Structured output (Strategy Brief)

Describe your current position and get a structured second opinion: diagnosis, recommended actions, risks, alternatives, assumptions, and next steps. The Civ VI advisor is the most polished first example of this output format; the other five advisors follow the same shape.

Feedback labels

After a recommendation comes back, six feedback buttons sit below the response: useful, not useful, I followed this, I ignored this, I changed my mind, AI missed something. Feedback buttons help the app understand whether the advice was useful — they're not required to use the advisor, but they shape how future versions behave.

How it works

1. 1Open /ai-gamefriend/decision-duel directly, or arrive via the Decision Duel card on Start Here (optionally with a sample scenario prefilled).
2. 2Describe your current game position in the context field (faction, year, threats, resources, the decision you're weighing).
3. 3Type your intended move first in the precommit field. The form blocks submission until you do — the whole point is to record your instinct before the AI says anything.
4. 4Submit. The AI returns: a recommendation, the reasoning behind it, a safe alternative, an aggressive alternative, what you may be missing, and the assumptions / limitations the recommendation rests on.
5. 5Mark a feedback label after reading: useful, not useful, I followed this, I ignored this, I changed my mind, AI missed something. The label helps the app understand whether the advice was useful.

What this is — and what it isn't

What this is: a structured comparison between your instinct and a written-out AI second opinion. Useful for big-decision turns where you want to slow down and sanity-check a plan, or for learning sessions where you want to see how an AI frames the same position you're staring at.

What this is NOT: a guarantee that either move is right. The AI doesn't see your game; it sees the words you typed. If your description is vague, the recommendation will be generic. If your description is specific, the recommendation can be too — but it's still a second opinion, not an oracle.

Experimental chess comparison

Pick two providers and personalities, click Start, and watch the match unfold turn by turn. The chess board renders the current position; each move shows the AI's reasoning and the running cost meter. The match terminates on real chess outcomes (checkmate, stalemate, draw by repetition, fifty-move rule, insufficient material) — not on a generic time-out.

Invalid AI output (rare but it happens) is logged to the spectator view as a fallback move and counted; if a provider produces repeated illegal output the match aborts honestly rather than silently making first-legal-move chess.

Strategy Briefs (STS, Dominions 6)

Open Watch → Strategy Briefs. Pick a Slay the Spire scenario (character + ascension + seed) and the AIs to compare. Each AI writes a 200-400-word strategic brief for the same scenario; you read them side by side and rank.

This is explicitly not AI-driven gameplay — no AI actually runs an STS climb here. Real per-AI STS competitions are not part of the basic release candidate.

Other comparison games

Other titles unlock as their game adapters mature. The comparison picker filters to supported games on purpose so users can't ask for something the engine can't deliver.

Prerequisites

• Slay the Spire installed via Steam.
• ModTheSpire + BaseMod + CommunicationMod from the Steam Workshop.
• Run STS once after subscribing so the mods generate their config files.

Setup (one time)

1. 1Subscribe to CommunicationMod in the Steam Workshop and launch STS once. The mod writes its config file on first launch.
2. 2In the AI-GameFriend install folder, run setup-sts.bat. It writes the relay command path to %LOCALAPPDATA%\\ModTheSpire\\CommunicationMod\\config.properties.
3. 3Restart STS. The Settings → About panel in AI-GameFriend should show the bridge as Reachable within ten seconds.

Running a mod-bridge climb

1. 1Open Watch → Slay the Spire single run.
2. 2Pick the AI provider, model, character (Ironclad / Silent / Defect / Watcher), ascension level, and a seed if you want a specific run.
3. 3Click Start run only if Watch is enabled and setup is complete. PASS means useful output or a clear setup-required message; FAIL means a raw internal/provider error or a hang.
4. 4The run ends on death, victory, or your abort. The result panel shows outcome, floors cleared, decisions made, and total cost.

Strategic Mind Profile

Six trait dimensions, refreshed after every match: tactical creativity, strategic discipline, leadership drive, diplomatic instinct, pressure response, and cooperation tendency. Each dimension is a number on [-1, 1]; together they produce a radar chart and a dominant trait.

Confidence gating

Until you've played enough matches for the profile to stabilise, your dominant trait reads Discovering rather than locking in early. Confidence rises as you play more games; the threshold is explicit so a single chess match doesn't pretend to know who you are.

You vs AI comparison

The web Personality Card at /quick-profile overlays your trait scores against four baseline AI styles (Claude, GPT, Grok, Gemini) on the same six dimensions. This is the smoothest end-to-end flow in the app — two minutes from open to share-ready card.

Privacy

Your profile lives on your device by default. The data-handling details — what's collected, how to revoke consent, how to request deletion — are at /privacy. The toggle in Settings → Privacy takes effect immediately.

Daily Challenge

One new dilemma every UTC day, the same prompt for everyone. Streak counter, share button, countdown to the next reset. Two minutes per day.

Council of AIs

Four AI personas argue a scenario from different angles; you pick which side won the debate. Useful when you want to feel out a decision from multiple perspectives at once. About five minutes.

Blitz

Ten dilemmas, five seconds each. System-1 mode — answer fast, think later. The classifier surfaces patterns you might suppress when you have more time. Under two minutes total.

Rule Twist

Five rounds where the rules change mid-run. Tracks how you adapt — strict planner, opportunistic, sunk-cost-driven, and so on. Five minutes.

The Mole

Four-player social deduction. You play with three AI personas; one of them (or you) is sabotaging missions. Find them, or play the mole well enough to escape suspicion. About ten minutes.

API Keys

One row per provider with a status badge. Each row has a Test button (validates against the provider) and a Change button (re-paste). Keys live in the Windows credential keychain; nothing is sent to our servers.

Default Provider

Pre-selects on every new match. Appears once you have at least two valid keys — pointless otherwise. Falls back gracefully if the saved default later becomes invalid.

Game Settings

Per-match defaults: difficulty, AI turn delay, whether to show AI thinking, and per-game model overrides where supported.

Privacy

Toggle anonymous match-decision sharing on or off. When on, anonymised game decisions go to the research database that powers profile accuracy; when off, nothing is sent. Revocation takes effect immediately. Full details at /privacy.

Data settings (added in v0.9.8)

On the web, /ai-gamefriend/data-settings lets you choose how much of your gameplay-decision feedback is saved. Three options:

• Operational only — minimal capture, just enough to keep the service running. Default.
• Product improvement — pseudonymous decision detail so the next version of the advice can be more specific.
• Research contribution — sanitised decision detail retained for longer-term study of how players and AIs reason about strategy games.

You can change the setting at any time. The product still works on operational only — disabling capture doesn't disable the advice itself. Full details at /privacy.

About

Live build version, CommunicationMod bridge status, OS, and a re-check button for the bridge. The STS setup runbook is linked from this panel.

10.1 STS bridge not detected

Symptoms: the STS mod-run setup screen reports the bridge as unreachable; the Settings → About bridge dot stays red.

• Confirm CommunicationMod is enabled in ModTheSpire's loader and BaseMod loaded before it.
• The relay listens on 127.0.0.1:8887. If something else owns the port, close it.
• Re-run setup-sts.bat from the AI-GameFriend install folder; it rewrites the config.properties path. Restart STS.
• Open relay_debug.log in the AI-GameFriend folder. The last twenty lines usually name the problem (wrong Node path, locked port, Java path with spaces).

10.2 Provider rate-limited or quota exceeded

Symptoms: Test in Settings returns "Invalid" or a quota message; a match stalls and the cost meter doesn't move.

• Re-paste the key with no leading or trailing whitespace.
• Check usage in your provider console (links in Getting Started).
• Gemini's free tier requires an AI Studio project — a Google Cloud project does not work.
• If you have multiple keys, switch the default in Settings → Default Provider.

10.3 Match hangs

Symptoms: the AI thinking spinner runs for over a minute without a move appearing.

• Click Abort on the match (Arena flows show a cancel button; single-player matches let you close the screen).
• Restart with the same options. Heavier reasoning models can intermittently take longer than thirty seconds; the next request usually succeeds.
• If the abort button doesn't respond, use Settings → About → Report a bug and include the version + screenshot of the stuck screen.

10.4 Web flow vs desktop flow

Some features live on one side or the other:

• Web only: Quick Profile + shareable Personality Card with the You-vs-AI overlay; the daily, council, blitz, twist, and mole challenges; the strategic advisors.
• Desktop only: basic chess where configured, experimental comparison surfaces, STS Watch, the Strategy Brief mode, and the Strategic Mind radar in the app.
• Cross-platform parity is future work. Until then, the right entry point depends on what you want — the web is the easiest first ten minutes; the desktop is where chess and Arena live.

Deferred after v0.9.9

• MindGame model-comparison mode — future work only; not part of the current public release-candidate scope.
• Verified import integration for at least one advisor — future work only; manual entry remains the current honest public claim.
• STS Watch acceptance after live Pan retest.
• Dungeon Lord game state machine — the grimoire / dungeon-floor loop that's currently stubbed. Returns the title to Play vs AI when it ships.

Investigating

• More experimental comparison games after adapters and UI pass verification.
• Mobile companion for Quick Profile + the daily.
• Discord bot integration for shared Council debates.

The full audit and triage list is in CODEX-AIGF-V099-LIVE-DOWNLOAD-BASIC-RELEASE-SAFETY-REPORT.md in the repo root, with closure status verified by CODEX-AIGF-V099-ALPHA-EXIT-RELEASE-CANDIDATE-HARDENING-REPORT.md.