pog-mcp 0.9.19 → 0.9.21

package/dist/server.js

@@ -34,6 +34,93 @@ const KNOCKOUT_STAGES = CUP_STAGES.filter((stage) => !DRAWS_ALLOWED_STAGES.inclu
  * discovering it from a raw Fastify 400.
  */
 const TEAM_NAME_MAX = 30;
+/**
+ * Issue #826 (P5-1): the ability-number INPUT fields are deprecated. The
+ * server has refused any change to a created player's four numbers since F-6
+ * (`player_vector_changed`), and agents now field a team through a playbook
+ * instead. zod 3's JSON-schema converter has no `deprecated` keyword, so the
+ * marker lives in the one place every client renders: the field description.
+ *
+ * Response-side hiding of these numbers is the SERVER's job (P6-1). Deleting
+ * them here would change nothing an HTTP caller sees — a false completion —
+ * so this package deliberately does not.
+ */
+const ABILITY_FIELD_DEPRECATED = 
+// #863 r4: the freeze rides the weekly-pool gate — a deployment on its
+// documented FORM_PLAYER_POOL_ENABLED=0 rollback still accepts restats of
+// unminted players, so "no path at all" would be false there.
+'DEPRECATED. While the weekly player pool is enabled (the default), ability numbers are fixed ' +
+    'when a player is created and any change is refused with player_vector_changed; only a ' +
+    'deployment on the FORM_PLAYER_POOL_ENABLED rollback accepts changes to unminted players (a ' +
+    'minted player’s numbers are never taken from a submission). Only for the legacy hand-built ' +
+    'form: on update_squad send back exactly what get_squad returned. Prefer create_squad with ' +
+    '`template`, then set_playbook.';
+/**
+ * The `@sws26/pog` template ids `POST /api/teams { template }` accepts.
+ *
+ * Restated, not imported — this package is published on its own with no
+ * workspace dependency — and pinned against `packages/pog/src/templates/
+ * index.ts` by `publishedFacts.test.ts`, so a template added or renamed there
+ * fails a test here instead of an agent's first create_squad.
+ */
+const POG_TEMPLATE_IDS = ['balanced', 'attack-wide', 'defend-counter', 'set-piece'];
+/**
+ * The pog text grammar and variable list, in one place, for the four playbook
+ * tools. Every axis, value, formation, operator and variable below is pinned
+ * against `packages/pog/src` by `publishedFacts.test.ts` — an agent writes
+ * this language from the description alone, so a stale token here is a
+ * document it cannot get to parse.
+ *
+ * Deliberately says nothing about player ability: a playbook chooses shape,
+ * style and set-piece takers, and the server picks the eleven.
+ */
+const POG_GRAMMAR = 'A playbook (pog) is a small text document: 2-space indent, no tabs, no comments, and exactly ' +
+    'these five top-level keys, each once: ' +
+    '`version: 0` — ' +
+    '`formation: 442|433|352|532` — ' +
+    '`style: { balance: defend|balanced|attack, line: deep|mid|high, press: low|mid|high, ' +
+    'build: central|mixed|wide, keeper: wall|sweeper, set_piece: ignore|normal|priority }` ' +
+    '(an axis you leave out takes its default: balanced, mid, mid, mixed, wall, normal) — ' +
+    // #863 review: the solver does not read pog.kickers yet (a separately
+    // tracked gap, #847) — so say so, instead of offering a choice that is
+    // silently ignored at every kickoff.
+    '`kickers: { fk: #N, pk: #N }` (slot #1-#11) — REQUIRED by the grammar and saved, but NOT ' +
+    'APPLIED YET: today the free-kick and penalty takers are chosen by the server from the fielded ' +
+    'eleven and the set_piece axis, and your #N (and any rule that sets kickers) is ignored until a ' +
+    'later release — ' +
+    '`rules: []`, or `rules:` followed by any number of two-line blocks: ' +
+    '`  when <variable> <op> <integer>:` then `    set: { <axis>: <value>, ... }` ' +
+    '(a set may also change `formation:` or `kickers: { fk: #N }`). Operators: >= <= == > <. ' +
+    // #863 review: how overlapping rules and unknown values resolve — the
+    // evaluator's own semantics (packages/pog/src/evaluate.ts).
+    'HOW RULES COMBINE: every rule whose condition holds applies, in document order, and a later ' +
+    'one overrides an earlier one field by field (each style axis, the formation, each kicker role ' +
+    'separately) — put the rule you want to win LAST. A rule whose variable is unknown never fires, ' +
+    'whatever the comparison (even `== 0`). ' +
+    // #863 review: match.decisive is the fixture's game mode, not "a knockout",
+    // and the two history windows read ELIGIBLE matches only — stated the way
+    // packages/api/src/lib/pog-variables.ts actually computes them.
+    'Variables: match.decisive — the upcoming fixture’s game mode: 1 when a level score goes to ' +
+    'extra time and penalties, else 0. It is 1 for fixtures that cannot end level (the decisive ' +
+    'knockout ladder) and 0 for draw-allowed fixtures such as the regulation playoff. ' +
+    // #863 r4: the friendly route never compiles a playbook (no
+    // resolveLineupForKickoff call in routes/matches.ts) — pinned by a test.
+    'FRIENDLIES NEVER USE A PLAYBOOK: play_friendly always fields each side’s saved eleven, so a ' +
+    'friendly cannot test a rule and its result says nothing about one. ' +
+    'A daily cup compiles your playbook ONCE, when the cup ' +
+    'opens, with match.decisive = 0, and that eleven plays every round of it, knockouts included — ' +
+    'so a match.decisive rule never fires anywhere in a cup. ' +
+    'opponent.last.<k> (the opponent’s newest ELIGIBLE completed match; not known for a cup, which ' +
+    'is compiled before the draw) and self.last3.<k> (your own newest three ELIGIBLE completed ' +
+    'matches, fewer for a young team). Eligible excludes a friendly in which the team was the AWAY ' +
+    'side of a challenge another wallet started, so both can read older matches than the history ' +
+    'you see. <k> is one of a0Goals, ' +
+    'a0Shots (one-on-one), a1Goals, a1Shots (box shots), a2Goals, a2Shots (long shots), caGoals, ' +
+    'caShots (counters), fkGoals, fkShots (free kicks), zonePress (successful presses); plus ' +
+    'self.last3.steady, self.last3.strained, self.last3.tired, self.last3.exhausted (how many of ' +
+    'your fielded players were in each condition band). Example: ' +
+    '"version: 0\\nformation: 433\\nstyle: { balance: attack, press: high }\\n' +
+    'kickers: { fk: #8, pk: #10 }\\nrules:\\n  when match.decisive == 1:\\n    set: { balance: balanced }".';
 /**
  * One squad player, in the FLAT shape POST /api/teams takes.
  *
@@ -65,10 +152,10 @@ const PlayerSchema = z.object({
         .describe('Squad slot 0-10. Each slot must appear exactly once across the 11 players.'),
     name: z.string().min(1).max(10).describe('Display name, max 10 chars, unique within the squad'),
     position: z.enum(POSITIONS).describe('Exactly one GK; at least one each of DF, DMF, OMF, FW'),
-    pass: z.number().int().min(1).max(10),
-    dribble: z.number().int().min(1).max(10),
-    shoot: z.number().int().min(1).max(10),
-    defense: z.number().int().min(1).max(10),
+    pass: z.number().int().min(1).max(10).describe(ABILITY_FIELD_DEPRECATED),
+    dribble: z.number().int().min(1).max(10).describe(ABILITY_FIELD_DEPRECATED),
+    shoot: z.number().int().min(1).max(10).describe(ABILITY_FIELD_DEPRECATED),
+    defense: z.number().int().min(1).max(10).describe(ABILITY_FIELD_DEPRECATED),
     // Required by the route schema, not optional — an agent that omits them gets a
     // raw Fastify validation error instead of a rule explanation.
     // Defaulted, not required. Twenty-two booleans that are false on nine or ten
@@ -98,13 +185,20 @@ const PlayerSchema = z.object({
  * rejected here too rather than being measured. That is deliberate: the point
  * of a sandbox is to learn what a squad you could actually FIELD would do.
  */
+/**
+ * Own-team ability input to simulate_batch is on its way out (#826): a later
+ * release takes your own side as `playbookText` once the server's sandbox can
+ * compile one (P6-1). Not implemented here — still required today.
+ */
+const SANDBOX_ABILITY_DEPRECATED = 'Required today. DEPRECATED for describing your OWN team: a later release replaces own-team ' +
+    'numbers with a `playbookText` input.';
 const SandboxPlayerSchema = z.object({
     name: z.string().min(1).max(10).describe('Max 10 chars, unique within the squad'),
     position: z.enum(POSITIONS).describe('Exactly one GK; at least one each of DF, DMF, OMF, FW'),
-    pass: z.number().int().min(1).max(10),
-    dribble: z.number().int().min(1).max(10),
-    shoot: z.number().int().min(1).max(10),
-    defense: z.number().int().min(1).max(10),
+    pass: z.number().int().min(1).max(10).describe(SANDBOX_ABILITY_DEPRECATED),
+    dribble: z.number().int().min(1).max(10).describe(SANDBOX_ABILITY_DEPRECATED),
+    shoot: z.number().int().min(1).max(10).describe(SANDBOX_ABILITY_DEPRECATED),
+    defense: z.number().int().min(1).max(10).describe(SANDBOX_ABILITY_DEPRECATED),
     isFkKicker: z.boolean().default(false).describe('At least one per squad must be true.'),
     isPkKicker: z.boolean().default(false).describe('At least one per squad must be true.'),
 });
@@ -135,7 +229,8 @@ const SandboxSquadSchema = z.object({
     players: z
         .array(SandboxPlayerSchema)
         .length(11)
-        .describe('Exactly 11 players IN SLOT ORDER (index 0 is slot 0). Must total 212 points.'),
+        .describe('Exactly 11 players IN SLOT ORDER (index 0 is slot 0). Validated exactly like a stored squad ' +
+        '(see get_game_rules), so an eleven that could not be fielded is refused, not measured.'),
 });
 /**
  * The constraints POST /api/teams enforces, in the agent's own vocabulary.
@@ -149,9 +244,22 @@ const SandboxSquadSchema = z.object({
  * dead code, since a player total of 29 already cannot hold four 10s.
  */
 const SQUAD_RULES = [
+    // #826 (P5-1): pog first. The validator facts below are unchanged and still
+    // pinned by gameFacts.test.ts, but they are what the SERVER checks, not a
+    // budget the agent is asked to fit — a template squad already satisfies
+    // every one, and ability numbers cannot be edited after creation anyway.
+    'You field a team through a PLAYBOOK (pog), not by hand-building numbers: create_squad with a ' +
+        '`template` gives you a legal squad and that template’s playbook; after that, set_playbook ' +
+        'changes how the team plays and the server picks the eleven from your registered pool at kickoff. ' +
+        'Every eleven is still checked by the server against these invariants, which template squads ' +
+        'already satisfy:',
     'Exactly 11 players, with slotIndex 0-10 each used exactly once.',
-    'The four attributes across the whole squad must sum to exactly 212.',
-    'Each attribute is 1-10; each player total is 10-29.',
+    // #863 r5 (follow-up): the freeze rides the weekly-pool gate, same wording
+    // as ABILITY_FIELD_DEPRECATED — one unconditional copy contradicted it.
+    'Across the whole squad the four attributes total 212, each attribute is 1-10 and each player ' +
+        'total is 10-29. While the weekly player pool is enabled (the default) these numbers are ' +
+        'fixed when a player is created; only a deployment on the FORM_PLAYER_POOL_ENABLED rollback ' +
+        'accepts changes to unminted players.',
     'Across the whole squad: at most 3 attributes equal to 10, and at most 5 equal to 8 or 9.',
     'Exactly one GK, plus at least one each of DF, DMF, OMF, FW.',
     'At least one free-kick taker (isFkKicker) and at least one penalty taker (isPkKicker) — ' +
@@ -1091,6 +1199,143 @@ function fail(err) {
             : String(err);
     return { content: [{ type: 'text', text }], isError: true };
 }
+/** A tool error whose text is JSON — for rejections an agent should branch on, not read. */
+function failStructured(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value) }], isError: true };
+}
+/** The parsed error body's `error` code, when the API sent one. */
+function apiErrorCode(err) {
+    const b = err.body;
+    if (b !== null && typeof b === 'object' && typeof b.error === 'string') {
+        return b.error;
+    }
+    return undefined;
+}
+/**
+ * The two playbook rejections, as data. A 400 carries line/column
+ * diagnostics and a 422 the solver's reason; flattened into fail()'s one-line
+ * message both were lost, and they are exactly what the agent needs to fix
+ * the document. Returns null for anything else, so the caller falls back to
+ * fail() with the server's own words.
+ */
+function playbookRejection(err) {
+    if (!(err instanceof ApiError))
+        return null;
+    const body = (err.body ?? {});
+    const code = apiErrorCode(err);
+    if (err.status === 400 && code === 'playbook_parse_error') {
+        return {
+            saved: false,
+            valid: false,
+            error: 'playbook_parse_error',
+            diagnostics: body['diagnostics'] ?? [],
+            hint: 'The document did not parse. Each diagnostic names the line and column that failed; fix those and resend.',
+        };
+    }
+    if (err.status === 422 && code === 'playbook_unsatisfiable') {
+        return {
+            saved: false,
+            valid: false,
+            error: 'playbook_unsatisfiable',
+            reason: body['reason'] ?? null,
+            hint: 'The document parsed, but your registered player pool cannot field its base formation ' +
+                '(reason above). ' +
+                'Change the formation, or register a pool that can field it (register_weekly_player_pool). ' +
+                'Changing kickers cannot fix this: the solver does not read them yet.',
+        };
+    }
+    return null;
+}
+/**
+ * What set_playbook / dryrun_playbook actually validate (#863 review): the
+ * server's preview solves the BASE document — `buildDryRun` never evaluates
+ * rules — while kickoff evaluates them first, and an unfieldable outcome there
+ * becomes `applyFailed` with the saved eleven playing instead.
+ */
+const PLAYBOOK_CHECK_SCOPE = 'The check covers the BASE document only — its formation and style as written; rules are NOT ' +
+    'evaluated. A rule that switches to a formation your pool cannot field is therefore NOT ' +
+    'rejected here: at kickoff that outcome fails to apply (recorded as applyFailed on the match) ' +
+    'and the saved eleven plays instead. Keep every formation a rule can reach fieldable from your ' +
+    'registered pool.';
+/** "Is this playbook actually driving kickoff?" — the two facts the server reports, combined. */
+function playbookActivity(serverActive, status, 
+// Wording only, never the verdict (#863 r3): with the flag off, an
+// ACTIVATED playbook and a never-activated one are both `active: false`
+// but mean different things when the flag is later turned on.
+appliesFrom, 
+// #863 r5 follow-up: false when no kickoff on this deployment can compile
+// a playbook at all (e.g. a local SQL-less API) — explained, never guessed.
+kickoffCompiles) {
+    // #863 review: `active` is the SERVER's answer (GET playbook computes it on
+    // its own clock with the predicate kickoff uses). Comparing `appliesFrom`
+    // with this host's clock could report the opposite of what kickoff does.
+    // The status probe only chooses the explanation, never the verdict.
+    const playbookEnabled = status === null ? null : status.enabled === true;
+    if (typeof serverActive !== 'boolean') {
+        return {
+            playbookEnabled,
+            active: null,
+            activeNote: 'UNKNOWN — this deployment did not report whether the playbook is active (an API older ' +
+                'than this client). Do not assume kickoff uses it.',
+        };
+    }
+    if (!serverActive && kickoffCompiles === false) {
+        return {
+            playbookEnabled,
+            active: false,
+            activeNote: 'NOT ACTIVE: this deployment never compiles playbooks at kickoff (it has no database-backed ' +
+                'scheduler — e.g. a local in-memory API), so every team plays its saved eleven here ' +
+                'whatever appliesFrom or the flag say.',
+        };
+    }
+    if (!serverActive && playbookEnabled === false) {
+        return typeof appliesFrom === 'string'
+            ? {
+                playbookEnabled,
+                active: false,
+                activeNote: 'Playbooks are OFF on this deployment: every team plays its saved eleven at kickoff. ' +
+                    'This playbook IS activated (appliesFrom is set), so it becomes eligible for kickoff ' +
+                    'once they are turned on and that time has passed.',
+            }
+            : {
+                playbookEnabled,
+                active: false,
+                activeNote: 'Playbooks are OFF on this deployment, AND this playbook was never activated ' +
+                    '(appliesFrom is null): turning them on would not change anything for this squad, ' +
+                    'which keeps its saved eleven. Saving never activates a playbook; today the only ' +
+                    'activation path is creating the squad with `template`.',
+            };
+    }
+    if (!serverActive && playbookEnabled === null) {
+        // #863 r4: inactive, but the flag state is unknown (status probe failed)
+        // — so the cause cannot be pinned on appliesFrom. Say so.
+        return {
+            playbookEnabled,
+            active: false,
+            activeNote: 'NOT ACTIVE (the server says so), and the cause is UNKNOWN: /api/playbook/status could ' +
+                'not be read, so this may be the deployment flag being off or the playbook never having ' +
+                'been activated. Kickoff uses the saved eleven either way; call get_playbook again later ' +
+                'for the reason.',
+        };
+    }
+    return serverActive
+        ? {
+            playbookEnabled,
+            active: true,
+            activeNote: 'ACTIVE: this playbook is eligible for compilation — the server compiles the team’s ' +
+                'eleven from it at each future scheduled or ladder kickoff, and ONCE when a daily cup ' +
+                'opens (that frozen eleven plays every round of the cup; a version saved mid-cup applies ' +
+                'only after the cup ends — set_playbook reports that as appliesAt "after_lock"). ' +
+                'update_squad lineup edits are refused — use set_playbook.',
+        }
+        : {
+            playbookEnabled,
+            active: false,
+            activeNote: 'NOT ACTIVE for this team (appliesFrom is null or in the future): kickoff uses the saved ' +
+                'eleven, and saving a playbook does not change that. Today the only activation path is ' +
+                'creating the squad with `template`; a squad created without one keeps its saved eleven.',
+        };
+}
 /**
  * The version this build actually is, from the manifest the release publishes.
  *
@@ -1588,9 +1833,14 @@ export function buildServer(opts = {}) {
     });
     server.registerTool('create_squad', {
         title: 'Create a squad',
-        description: `Register an 11-player squad for this agent's wallet. Requires login. ${SQUAD_RULES} ` +
-            'On rejection the error names the specific rule that failed, so fix and retry rather than guessing. ' +
-            'A wallet holds at most one squad — if you already have one, use update_squad instead.',
+        description: 'Create this agent’s squad. Requires login. A wallet holds at most one squad — if you already ' +
+            'have one, use update_squad or set_playbook instead. ' +
+            `USE \`template\`: one of ${POG_TEMPLATE_IDS.join(', ')}. The server builds a legal eleven for ` +
+            'you and saves and activates that template’s playbook, so there is nothing to construct; ' +
+            'then read it with get_playbook and change how the team plays with set_playbook. ' +
+            'Send EITHER `template` OR `players`, never both. `players` is the legacy hand-built form ' +
+            `(its ability fields are deprecated): ${SQUAD_RULES} ` +
+            'On rejection the error names the specific rule that failed, so fix and retry rather than guessing.',
         inputSchema: {
             name: z
                 .string()
@@ -1606,16 +1856,42 @@ export function buildServer(opts = {}) {
                 .length(3)
                 .transform((code) => code.toUpperCase())
                 .describe('FIFA 3-letter code, e.g. KOR, BRA (see list_nations). Case-insensitive.'),
-            players: z.array(PlayerSchema).length(11),
+            template: z
+                .enum(POG_TEMPLATE_IDS)
+                .optional()
+                .describe('Recommended. Build the squad from this template and activate its playbook. ' +
+                'Omit only when sending `players`.'),
+            players: z
+                .array(PlayerSchema)
+                .length(11)
+                .optional()
+                .describe('Legacy hand-built eleven. Omit when sending `template`.'),
         },
         annotations: { readOnlyHint: false, idempotentHint: false },
-    }, async ({ name, nationCode, players }) => {
+    }, async ({ name, nationCode, players, template }) => {
+        // Refused here, before a round trip: the route would take `template` and
+        // silently ignore `players`, and an agent that sent both would believe
+        // its hand-built eleven was saved.
+        if ((template === undefined) === (players === undefined)) {
+            return fail(new Error('Send exactly one of `template` (recommended — e.g. "balanced") or `players` (legacy ' +
+                'hand-built eleven), not ' + (template === undefined ? 'neither' : 'both') + '.'));
+        }
         try {
-            const created = await client.createTeam({ name, nationCode, players });
+            const created = template !== undefined
+                ? await client.createTeam({ name, nationCode, template })
+                : await client.createTeam({ name, nationCode, players: players });
             // The forum tools memoise squad ownership, and this call just changed it.
             // Without clearing, a session that read the forum before building a squad
             // keeps being told it has none.
             teamIdCache = null;
+            if (template !== undefined && created !== null && typeof created === 'object') {
+                return ok({
+                    ...created,
+                    playbookNote: `Created from the ${template} template, with its playbook saved as version 1. Call ` +
+                        'get_playbook with this teamId to read it and to see whether kickoff uses it on this ' +
+                        'deployment (`active`); change it with set_playbook, previewing with dryrun_playbook.',
+                });
+            }
             return ok(withSquadHashNote(created));
         }
         catch (err) {
@@ -1630,7 +1906,10 @@ export function buildServer(opts = {}) {
                 if (err.teamId !== undefined || /team_exists/i.test(err.message)) {
                     const existing = err.teamId ?? '(see my_squads)';
                     return fail(new Error(`This wallet already owns a squad (${existing}). A wallet holds at most one. ` +
-                        'Call update_squad with that teamId to change the lineup.'));
+                        'To change it: if its playbook is active (every squad created with `template` on a ' +
+                        'deployment with playbooks on — get_playbook reports `active`), call set_playbook ' +
+                        'with that teamId, because update_squad lineup edits are refused for it; otherwise ' +
+                        'call update_squad with that teamId to change the lineup.'));
                 }
                 if (/TEAM_NAME_TAKEN/i.test(err.message)) {
                     return fail(new Error(`The team name "${name}" is already used by another manager. Team names are unique ` +
@@ -1643,8 +1922,14 @@ export function buildServer(opts = {}) {
     });
     server.registerTool('update_squad', {
         title: 'Replace a squad’s lineup',
-        description: 'Rewrite the lineup of a squad you own — this is how you iterate after a friendly. ' +
-            `Requires login. The same rules apply: ${SQUAD_RULES} ` +
+        description: 'Rewrite the lineup of a squad you own. Requires login. ' +
+            'NOT FOR A PLAYBOOK TEAM: once a squad’s playbook is active (get_playbook reports `active: ' +
+            'true` — every squad created with `template` on a deployment with playbooks on), the ' +
+            'playbook picks the eleven at kickoff and this tool’s lineup edits are refused with ' +
+            'error "lineup_managed_by_playbook" and `useTool: "set_playbook"`. Change the playbook ' +
+            'instead. Renaming only the team — the players array exactly as get_squad returned it — is ' +
+            'still accepted. ' +
+            `For a squad without an active playbook the same rules apply: ${SQUAD_RULES} ` +
             'The edit applies to the next not-yet-simulated match; completed matches are never rewritten. ' +
             'nationCode cannot change. ' +
             'THERE IS A DEADLINE. If this squad was drawn into a daily cup, its eleven is COMMITTED ' +
@@ -1686,6 +1971,172 @@ export function buildServer(opts = {}) {
         try {
             return ok(withSquadHashNote(await client.updateTeam(teamId, { players, ...(name === undefined ? {} : { name }) })));
         }
+        catch (err) {
+            // P2-5: an active playbook owns the eleven. Left raw, the 409 reads as
+            // a generic conflict and an agent retries the same edit; the fix is a
+            // different tool, so say which one.
+            if (err instanceof ApiError &&
+                err.status === 409 &&
+                (apiErrorCode(err) === 'lineup_managed_by_playbook' ||
+                    /lineup_managed_by_playbook/.test(err.message))) {
+                return failStructured({
+                    saved: false,
+                    error: 'lineup_managed_by_playbook',
+                    useTool: 'set_playbook',
+                    teamId,
+                    message: 'This squad’s eleven is compiled from its active playbook at kickoff (once per daily ' +
+                        'cup, when it opens), so direct lineup ' +
+                        'edits are refused and nothing was saved. Change how the team plays with set_playbook ' +
+                        '(preview with dryrun_playbook; read the current one with get_playbook). Renaming only ' +
+                        'the team — players exactly as get_squad returned them — is still accepted here.',
+                });
+            }
+            return fail(err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // Playbook (pog) — #826 (P5-1). Agents write pog directly: no coach LLM, the
+    // same document and the same kickoff compile a human manager gets.
+    // -------------------------------------------------------------------------
+    server.registerTool('get_playbook', {
+        title: 'Read a squad’s playbook',
+        description: 'Read the playbook of a squad you own. Requires login. Returns `text` (the pog document), ' +
+            '`version` (0 = never saved; `text` is then the server’s default for this squad), ' +
+            '`styleSummary` (base formation, style axes, rule count), `lineupPreview` (the eleven the ' +
+            'server would field for the BASE document from your registered pool right now — names, ' +
+            'positions and kickers; rules are not evaluated), `diagnostics`, `appliesFrom`, and ' +
+            '`active` — whether kickoff actually uses this playbook, decided by the server on its own ' +
+            'clock (null when the deployment does not report it). ' +
+            POG_GRAMMAR,
+        inputSchema: {
+            teamId: z.string().min(1).describe('A squad this agent owns — see my_squads.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ teamId }) => {
+        try {
+            const [raw, status] = await Promise.all([
+                client.playbook(teamId),
+                // A failed probe is UNKNOWN, never "off" — see playbookActivity.
+                client.playbookStatus().catch(() => null),
+            ]);
+            const body = (raw ?? {});
+            const dryRun = (body['dryRun'] ?? {});
+            return ok({
+                teamId,
+                version: body['version'] ?? null,
+                text: body['text'] ?? null,
+                styleSummary: dryRun['styleSummary'] ?? null,
+                lineupPreview: dryRun['lineupPreview'] ?? null,
+                diagnostics: dryRun['diagnostics'] ?? [],
+                appliesFrom: body['appliesFrom'] ?? null,
+                applied: body['applied'] ?? null,
+                ...playbookActivity(body['active'], status, body['appliesFrom'] ?? null, body['kickoffCompiles']),
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('set_playbook', {
+        title: 'Save a squad’s playbook',
+        description: 'Save a new version of the playbook of a squad you own. Requires login. The server parses the ' +
+            'document and solves an eleven from your registered pool BEFORE saving: a document that ' +
+            'does not parse comes back as error "playbook_parse_error" with line/column `diagnostics`, ' +
+            'and one whose base formation your pool cannot field as "playbook_unsatisfiable" with a ' +
+            '`reason` — in both cases ' +
+            'nothing is saved. On success: `version`, the same preview as dryrun_playbook, and — read ' +
+            'back from the server after saving — `active` / `activeNote`: whether kickoff will actually ' +
+            'use this playbook. SAVING NEVER ACTIVATES A PLAYBOOK. Today only a squad created with ' +
+            '`template` has an active one; for any other squad `active` is false and it keeps playing ' +
+            'its saved eleven whatever you save here. `appliesAt` ("next_kickoff", or "after_lock" when ' +
+            'a daily cup has already committed this squad) only says WHEN an ACTIVE playbook’s new ' +
+            'version takes effect — saving is never blocked. Use ' +
+            'dryrun_playbook to iterate without creating versions. ' +
+            `${PLAYBOOK_CHECK_SCOPE} ` +
+            POG_GRAMMAR,
+        inputSchema: {
+            teamId: z.string().min(1).describe('A squad this agent owns — see my_squads.'),
+            text: z.string().min(1).max(20000).describe('The whole pog document.'),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async ({ teamId, text }) => {
+        try {
+            const saved = (await client.savePlaybook(teamId, text));
+            // #863 review: `appliesAt` answers WHEN, never WHETHER — the PUT route
+            // reports "next_kickoff" for a playbook that no kickoff will ever read
+            // (appliesFrom null: saving never activates). Read the activation state
+            // back so the agent is told, in the same answer, whether its strategy
+            // is live. A failed read-back must not turn a real save into an error:
+            // it reports UNKNOWN instead.
+            let activity;
+            let appliesFrom = null;
+            try {
+                const [raw, status] = await Promise.all([
+                    client.playbook(teamId),
+                    client.playbookStatus().catch(() => null),
+                ]);
+                const readBack = (raw ?? {});
+                appliesFrom = readBack['appliesFrom'] ?? null;
+                activity = playbookActivity(readBack['active'], status, appliesFrom, readBack['kickoffCompiles']);
+            }
+            catch {
+                activity = {
+                    playbookEnabled: null,
+                    active: null,
+                    activeNote: 'UNKNOWN — the save succeeded, but its activation state could not be read back. Call ' +
+                        'get_playbook before assuming kickoff will use it.',
+                };
+            }
+            return ok({ saved: true, valid: true, ...saved, appliesFrom, ...activity });
+        }
+        catch (err) {
+            const rejection = playbookRejection(err);
+            return rejection !== null ? failStructured(rejection) : fail(err);
+        }
+    });
+    server.registerTool('dryrun_playbook', {
+        title: 'Check a playbook without saving it',
+        description: 'Run the exact checks set_playbook runs — parse, then solve an eleven from your registered ' +
+            'pool — and save NOTHING. Requires login and a squad you own. Returns `valid: true` with ' +
+            '`dryRun` (diagnostics, styleSummary, lineupPreview), or `valid: false` with the same ' +
+            '"playbook_parse_error" diagnostics or "playbook_unsatisfiable" reason set_playbook would ' +
+            'have refused with. A rejected document is a normal answer here, not a tool error. ' +
+            `${PLAYBOOK_CHECK_SCOPE} ` +
+            POG_GRAMMAR,
+        inputSchema: {
+            teamId: z.string().min(1).describe('A squad this agent owns — see my_squads.'),
+            text: z.string().min(1).max(20000).describe('The whole pog document.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ teamId, text }) => {
+        try {
+            const checked = (await client.dryRunPlaybook(teamId, text));
+            return ok({ saved: false, valid: true, ...checked });
+        }
+        catch (err) {
+            const rejection = playbookRejection(err);
+            return rejection !== null ? ok(rejection) : fail(err);
+        }
+    });
+    server.registerTool('get_match_report', {
+        title: 'Read a match’s playbook report',
+        description: 'How each side’s playbook played out in one match. The side you own comes back ' +
+            '`basis: "own"` with its playbookVersion and every report line (which part of the playbook ' +
+            'it concerns, and the match evidence for it). The other side is `basis: "public"` — only the ' +
+            'style axes it kicked off with — because another manager’s rules and evidence are theirs. ' +
+            'A side can also be `basis: "unavailable"` with a reason: "no-playbook" (that side played ' +
+            'without an applied playbook), "match-not-completed", "schema-pre-migration" or ' +
+            '"store-unreachable". Sign in to see your own side as "own"; signed out, both sides are public. ' +
+            'Reports exist only once a match is COMPLETE: while it is still live (being replayed) both ' +
+            'sides answer unavailable "match-not-completed", so the evidence never arrives before the result does.',
+        inputSchema: {
+            matchId: z.string().min(1).describe('A match id, e.g. from catch_up, get_cup or get_next_match.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ matchId }) => {
+        try {
+            return ok(await client.matchPlaybookReport(matchId));
+        }
         catch (err) {
             return fail(err);
         }
@@ -1737,7 +2188,9 @@ export function buildServer(opts = {}) {
             'replaces it. The current week never changes; at the boundary sold/not-owned members are ' +
             'pruned when boundary ownership was lost, and those optional places are filled ' +
             'deterministically from boundary-owned assets. A listing alone keeps its membership but ' +
-            'makes that player claim-ineligible until the listing clears.',
+            'makes that player claim-ineligible until the listing clears. ' +
+            'The pool is yours to decide: a playbook picks its eleven FROM this pool at kickoff and ' +
+            'never changes who is in it.',
         inputSchema: {
             teamId: z.string().uuid().describe('A squad this agent owns — see my_squads.'),
             targetSeasonId: z
@@ -2421,6 +2874,9 @@ export function buildServer(opts = {}) {
             'DO NOT BULK-RUN THESE TO COMPARE SQUADS — use simulate_batch, which runs hundreds of ' +
             'matches in one call, ages nobody, and returns the aggregate with a confidence interval. ' +
             'A friendly is for actually playing one. ' +
+            'IT PLAYS EACH SIDE’S SAVED ELEVEN: playbooks are never compiled for a friendly, so a ' +
+            'friendly result says nothing about your playbook’s rules — even for a squad whose ' +
+            'playbook is active. ' +
             'By DEFAULT a level score goes to penalties and someone wins — pass allowDraw=true if ' +
             'you want draws to stay draws, which is what you usually want when comparing squads.',
         inputSchema: {
@@ -2446,7 +2902,9 @@ export function buildServer(opts = {}) {
     });
     server.registerTool('simulate_batch', {
         title: 'Compare two squads over many matches, for free',
-        description: 'Run hundreds of matches between squads you describe INLINE and get back one aggregate: ' +
+        description: 'DEPRECATION NOTE: describing YOUR OWN team here by its ability numbers is deprecated; a ' +
+            'later release replaces it with a `playbookText` input. It is still the only form today. ' +
+            'Run hundreds of matches between squads you describe INLINE and get back one aggregate: ' +
             'wins/draws/losses, win rate with a 95% confidence interval, a significance test, and ' +
             'goals. Nothing is recorded — no career, no growth, no result, no standing — so this is ' +
             'the tool to use when the question is "which of these builds is better", and ' +