pog-mcp 0.9.23 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog — pog-mcp
+
+## 1.1.0 — 2026-09-15
+
+- **`create_squad` refuses `players` on a deployment with playbooks on (#882).**
+  There the server builds squads only from a `template`; a hand-built eleven is
+  answered with a structured `{ error: "template_required", useField: "template",
+  templates: [...] }` and nothing is created, so the same call with `template` is
+  a safe retry. The refusal is the server's: the tool sends the request and maps
+  the `template_required` answer, so a signed-out, expired or server-revoked
+  session still gets "call login first" / its 401. With playbooks off,
+  `players` behaves exactly as in 1.0.0.
+
+## 1.0.0 — 2026-09-14
+
+**Agents field a team through a playbook. Player numbers are no longer an agent
+input.** The migration guide is the Skill's own section,
+[`skill/SKILL.md` → "What changed in 1.0"](skill/SKILL.md).
+
+The tool surface is the one 0.9.22 shipped. What 1.0.0 adds is the contract:
+the Skill and README are rewritten around it, and the major version says out
+loud that the changes below break a 0.x workflow — some of them arrived in
+0.9.20–0.9.22 under minor versions, which understated them.
+
+### Breaking
+
+- **The Skill no longer publishes squad-building advice.** The ability-allocation
+  guidance, the engine expressions (keeper and kicker arithmetic), the
+  scarce-value budget table and the related rules of thumb were removed, not
+  corrected: numbers are fixed when a player is created, so there is nothing
+  left to allocate. The measurements remain, marked as history, in
+  `skill/reference/measurements.md`.
+- **`create_squad` takes `template`.** Send exactly one of `template` (`balanced`,
+  `attack-wide`, `defend-counter`, `set-piece`) or the legacy `players` array; the
+  tool refuses both and neither. A template squad has its playbook saved and
+  activated.
+- **`update_squad` is not how a playbook squad changes.** Once a squad's playbook
+  is active, lineup edits are refused with `lineup_managed_by_playbook` and
+  `useTool: "set_playbook"`; a rename that sends the players back unchanged still
+  goes through.
+- **Ability input fields are deprecated** on `create_squad` (`players`),
+  `update_squad` and, for your own side, `simulate_batch`. While the weekly pool
+  is enabled any change to a created player's numbers is refused with
+  `player_vector_changed`. A later release replaces your own side in
+  `simulate_batch` with playbook text.
+
+### Added (shipped in 0.9.20–0.9.22, first documented here)
+
+- `get_playbook`, `set_playbook`, `dryrun_playbook`, `get_match_report`.
+- A playbook's `kickers` is an override the server honors (0.9.22, #864): each
+  of `fk`/`pk` is optional, a written role is forced, a left-out one is picked
+  automatically by `set_piece`, an override that cannot be resolved keeps the
+  automatic pick with a `kickerFallback` warning instead of failing, and
+  `kickers: { fk: auto }` in a rule hands a role back. `#1` is the goalkeeper.
+
+### What this release cannot take back
+
+Every 0.x tarball on npm still carries the old Skill, and npm does not allow a
+published version to be edited. Minted players' numbers stay public in their
+permanent on-chain metadata by design; past API responses and the npm version
+history cannot be recalled. The Skill's "What cannot be taken back" section says
+the same to agents.

package/README.md

@@ -6,13 +6,23 @@ this adds is that the agent no longer has to read a runbook, hold a Solana
 keypair, or guess payload shapes.
 
 ```
-login → get_game_rules → create_squad → play_friendly → get_match
-                              ↑                    │
-                              └─── update_squad ───┘
+login → create_squad(template) → get_playbook → set_playbook → play_playoff → get_match_report
+                                                     ↑                                  │
+                                                     └──────────── revise ──────────────┘
 ```
 
-That loop back is the game. A wallet holds one squad; you improve it by playing
-friendlies and rewriting the lineup, not by building new teams.
+That loop back is the game. A wallet holds one squad, and every player's numbers
+are fixed once the player is created (while the weekly player pool is enabled,
+which is the default). You change how the squad plays by revising its playbook —
+formation, style and conditional rules. Where that playbook is active
+(`get_playbook` reports `active`; playbooks are a deployment switch, off unless
+the operator turns it on), the server compiles it at each ranked or scheduled
+kickoff — and for a daily cup ONCE, when the cup opens, into an eleven that plays
+every round. You do not build new teams, and you do not rewrite numbers.
+
+**1.0 is a breaking release** for anyone driving 0.x: see
+[`CHANGELOG.md`](CHANGELOG.md), and the Skill's "What changed in 1.0" section for
+the migration.
 
 Across sessions the wallet file is the account, so the agent returns as the same
 manager. Cups and league fixtures resolve on a scheduler, hours after they start,
@@ -126,8 +136,8 @@ the kind of thing a refactor breaks silently.
 | `revoke_sessions` | — | End one session by tag, or all of them. Also signs with the key rather than the current token, so a stolen token cannot sign the owner out. |
 | `get_game_rules` | — | Squad constraints and how the daily cup works. Read before building. |
 | `list_nations` | — | Code→name map. Pass `nationCode` for that nation's name pools. |
-| `create_squad` | ✓ | 11 players, 212 points. One squad per wallet — a second attempt redirects you to `update_squad`. |
-| `update_squad` | ✓ | Rewrite the lineup you own. Applies to the next unsimulated match. |
+| `create_squad` | ✓ | Send `template` (`balanced`, `attack-wide`, `defend-counter`, `set-piece`): the server builds a legal squad and activates that template's playbook. The hand-built `players` form is legacy and its ability fields are deprecated. One squad per wallet — a second attempt tells you which tool changes the one you have. |
+| `update_squad` | ✓ | Rewrite the lineup of a squad WITHOUT an active playbook; once one is active, lineup edits are refused with `lineup_managed_by_playbook` — use `set_playbook`. While the weekly pool is enabled (the default) a change to any player's numbers is refused with `player_vector_changed`; only that pool's rollback accepts changes to unminted players. Applies to the next unsimulated match. |
 | `my_squads` | ✓ | Squads owned by this wallet. |
 | `get_playbook` | ✓ | Your squad's playbook (pog) text, version, style summary, lineup preview, and whether kickoff actually uses it. |
 | `set_playbook` | ✓ | Save a new playbook version. Parse errors and unsatisfiable documents come back as structured data and save nothing. |
@@ -155,12 +165,13 @@ the kind of thing a refactor breaks silently.
 ## The Skill
 
 MCP gives an agent the ability to act; it does not give it judgment. An agent
-with only these tools builds a squad by splitting 212 points evenly across
-eleven players, which is measurably the worst thing you can build.
+with only these tools writes a playbook without knowing which style axes are
+decisions and which only need getting right once — and tries to test a rule with
+a friendly, which never uses a playbook at all.
 
-`skill/SKILL.md` is the other half: what the engine actually rewards, and how
-many friendlies a conclusion needs before it means anything. Install it for
-Claude Code with
+`skill/SKILL.md` is the other half: how to write a playbook and read the report
+after a match, and how many results a conclusion needs before it means anything.
+Install it for Claude Code with
 
 ```bash
 tgz="$(npm pack pog-mcp --silent)" && tar -xzf "$tgz" \

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAKL,SAAS,EAIV,MAAM,aAAa,CAAC;AAQrB,OAAO,EAQL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAohDrB,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAyBD,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,SAAS,CA+iHpE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAKL,SAAS,EAIV,MAAM,aAAa,CAAC;AAQrB,OAAO,EAQL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAuiDrB,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAyBD,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,SAAS,CA0jHpE"}

package/dist/server.js

@@ -1211,6 +1211,23 @@ function fail(err) {
 function failStructured(value) {
     return { content: [{ type: 'text', text: JSON.stringify(value) }], isError: true };
 }
+/**
+ * #882 (3A) — create_squad's answer when the deployment builds squads only from
+ * a template. Structured so an agent branches on `useField` instead of parsing
+ * prose; nothing was created, so a retry with `template` is safe.
+ */
+function templateRequired() {
+    return {
+        created: false,
+        error: 'template_required',
+        useField: 'template',
+        templates: [...POG_TEMPLATE_IDS],
+        message: 'This deployment has playbooks on, so a squad is built from a template, not from a ' +
+            'hand-built players array. Nothing was created. Call create_squad again with the same ' +
+            `name and nationCode and \`template\` set to one of ${POG_TEMPLATE_IDS.join(', ')}; then ` +
+            'change how the team plays with set_playbook.',
+    };
+}
 /** The parsed error body's `error` code, when the API sent one. */
 function apiErrorCode(err) {
     const b = err.body;
@@ -1848,7 +1865,9 @@ export function buildServer(opts = {}) {
             '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} ` +
+            'and is REFUSED on a deployment with playbooks on (get_playbook reports `playbookEnabled`): ' +
+            'there the answer is `template_required` with `useField: "template"` and nothing is created. ' +
+            `Where it is still accepted 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
@@ -1885,6 +1904,12 @@ export function buildServer(opts = {}) {
             return fail(new Error('Send exactly one of `template` (recommended — e.g. "balanced") or `players` (legacy ' +
                 'hand-built eleven), not ' + (template === undefined ? 'neither' : 'both') + '.'));
         }
+        // #882 (3A) — no client-side preflight. With playbooks on, the SERVER
+        // refuses a hand-built eleven (template_required, mapped in the catch
+        // below), and only for a live session — so a signed-out, expired or
+        // server-revoked session still gets its 401 and the agent is told to log
+        // in. Review r2/r3 (P2): a preflight against the public status route
+        // could not know the session's server-side state and masked those 401s.
         try {
             const created = template !== undefined
                 ? await client.createTeam({ name, nationCode, template })
@@ -1911,6 +1936,9 @@ export function buildServer(opts = {}) {
             // agent whose only problem was a duplicate team name to go call
             // update_squad with a teamId it does not have — a dead end, when the fix
             // was simply to pick another name.
+            if (err instanceof ApiError && err.status === 400 && apiErrorCode(err) === 'template_required') {
+                return failStructured(templateRequired());
+            }
             if (err instanceof ApiError && err.status === 409) {
                 if (err.teamId !== undefined || /team_exists/i.test(err.message)) {
                     const existing = err.teamId ?? '(see my_squads)';