gutcheck 0.1.0__tar.gz

gutcheck-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

gutcheck-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include gutcheck/doctrine.md
+recursive-include gutcheck/static *

gutcheck-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: gutcheck
+Version: 0.1.0
+Summary: A poker reading trainer: commit your read, then see the real equity.
+Author: Phill Clapham
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/phillipclapham/gutcheck
+Project-URL: Source, https://github.com/phillipclapham/gutcheck
+Project-URL: Issues, https://github.com/phillipclapham/gutcheck/issues
+Keywords: poker,trainer,equity,holdem,mcp
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pokerkit==0.7.4
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.28.0; extra == "mcp"
+Provides-Extra: anneal
+Requires-Dist: anneal-memory<2,>=0.8.5; extra == "anneal"
+Provides-Extra: api
+Requires-Dist: anthropic<1,>=0.112.0; extra == "api"
+Requires-Dist: openai<3,>=2.0.0; extra == "api"
+Dynamic: license-file
+
+# gutcheck
+
+**A poker reading trainer.**
+
+![Log a read, commit it, see the real number](https://raw.githubusercontent.com/phillipclapham/gutcheck/main/docs/gutcheck-loop.gif)
+
+You sit at a 6-max no-limit cash table against five bots. Each one plays a real, exploitable style: the rock, the reg, the calling station. The catch is that their names get shuffled against their styles every session, so you can't memorize who's who. You have to read them from how they play.
+
+Then, when it's your turn, you commit a read. How strong am I here? Is that guy actually on something? The trainer locks in what your gut said and shows you the real number, computed in code, never guessed. You see the gap. Do that a few hundred times and your feel for a table starts to line up with what's actually true.
+
+No account, no API key, no LLM needed. The bots are code and the equity math is exact. There's an optional AI coach if you want someone to talk the spot through with you, but the training loop never depends on it.
+
+```bash
+pip install gutcheck
+gutcheck
+```
+
+That opens a table in your browser at `http://127.0.0.1:8777`. Everything runs on your machine.
+
+## Play with Claude in the room
+
+This is how I actually use it. Start `gutcheck`, then open a Claude Code session with the gutcheck MCP server added (`pip install "gutcheck[mcp]"`, then `claude mcp add gutcheck -- gutcheck-mcp`, once). Now Claude can see the table you're sitting at, your hand history and your read stats, and you just talk it out while you play. What do you make of the guy who keeps check-raising? Was that fold as bad as it felt? Where are my reads drifting?
+
+It answers from what's actually on the table and in your history, not from vibes. And it only knows what you could know: the bots' hidden styles stay hidden, and it never sees their cards mid-hand, so it can't read them for you. It has to read them with you. It can't play your hands either. The clicking stays yours.
+
+## Why this exists
+
+I play by feel. Most of what happens at a poker table happens faster than I can do math, and I've always thought that was fine, since the gut is doing real work. But a gut that never gets checked isn't a skill. It's a mood.
+
+Solvers tell you the right play. They don't tell you how far off your read was, and that's the part I actually wanted to train. So gutcheck is built around one loop: **predict, check against ground truth, notice the gap, go again.** You commit before you see the answer, every time, so you can't fudge it after the fact.
+
+That loop isn't really about poker. It's the same thing whether you're reading a table, a codebase, or a room: say what you think is true, check it against something that can't lie to you, keep score. Poker just makes the scoring cheap and the ground truth exact.
+
+## How you train
+
+1. **Sit down.** A buy-in comes off your play-money bankroll and you get a fresh table.
+2. **Play.** Click any player to see what you've *observed* (VPIP, aggression, showdowns), never their hidden type. Guess it. There's a reveal button for checking yourself.
+3. **Log a read.** On your turn, hit **Log read ♠**. Set your gut equity on a slider in plain language ("behind", "a coin flip", "a favorite"), pick your lean, add a note if you want. Then the trainer shows you the modeled equity and names the gap.
+4. **Review.** After a hand, **⟳ review** replays it and stops at each of your decisions. Commit your gut again, then see the *exact* equity with every runout enumerated against the cards they really held.
+5. **Get up.** Cash out. A session report records your results, your biggest pots, and how your reads graded out per villain.
+
+Equity shows up as a felt band first ("a favorite") and the percentage second. The point is to train the feel, not to turn you into a calculator.
+
+Over time the **🎯 Reads** view tracks your calibration: all-time accuracy, the recent arc, and whether you're sharpening or drifting.
+
+## The optional coach
+
+When you want the *why*, hit **talk it through ♠** after a read and a coach walks through the spot, using the same number you just saw.
+
+Out of the box the coach tries the `claude` CLI if you have it (it rides your own Claude subscription). If it can't reach anything, it falls back to a plain facts readout: your equity band, the pot odds, what you've observed about each player. That always works, and the startup line tells you which one you're getting.
+
+Worth knowing: the `claude` provider runs a normal `claude -p` call, so your own `~/.claude/CLAUDE.md` loads with it. If that file says who you are, the coach knows you. It also means the spot you're asking about goes to whichever provider you picked, same as anything else you'd send it.
+
+Open **⚙ Settings** to pick a different provider:
+
+| Provider | What you need |
+|---|---|
+| Claude (default) | the `claude` CLI (Claude Code), logged in |
+| Codex | the `codex` CLI, logged in |
+| Anthropic API | `pip install "gutcheck[api]"` and your own API key |
+| OpenAI API | `pip install "gutcheck[api]"` and your own API key |
+
+API keys are stored locally in a file only you can read (`0600`) and never go back out through the settings API. Coaching can be switched off entirely in Settings if you'd rather just see the facts.
+
+**Leak memory.** With `pip install "gutcheck[anneal]"`, the coach also keeps a memory of your recurring mistakes. When the same misread shows up enough times, it gets a name ("fold reads undercount own equity"), cited back to the exact hands, and it graduates as it keeps happening. Next time you're in that spot, the coach brings it up. It's built on [anneal-memory](https://pypi.org/project/anneal-memory/).
+
+## Use it from Claude or another MCP client
+
+`pip install "gutcheck[mcp]"` adds `gutcheck-mcp`, an MCP server that lets an AI client read your table, your hand history and your calibration, and coach from them. It's read-mostly on purpose: the coach can see what you've observed, not the bots' hidden types, so it can't cheat for you.
+
+Start `gutcheck` first (the MCP server talks to it on port 8777), then register the MCP server. For Claude Code:
+
+```bash
+claude mcp add gutcheck -- gutcheck-mcp
+```
+
+For Claude Desktop or any other client, add a stdio server whose command is `gutcheck-mcp`.
+
+## Where your data lives
+
+```
+~/.gutcheck/
+    career.json          bankroll + lifetime stats
+    session.json         the table you're sitting at
+    sessions/<id>.json   session reports
+    calibration.json     your read accuracy over time
+    history.db           every hand you've played
+    coach.db             the local coach channel
+    settings.json        your settings
+    secrets.json         API keys, if you add any (0600)
+    leaks.db             leak memory, with the [anneal] extra
+```
+
+Set `GUTCHECK_DATA_DIR` to put it somewhere else. `gutcheck --reset` starts you fresh: it deletes the hand history, session reports and the current table, and keeps a one-step backup of your bankroll, read accuracy and leak memory in case you didn't mean it.
+
+## Flags
+
+| Flag | Does |
+|---|---|
+| `--port 8777` | change the port |
+| `--reset` | fresh start (deletes hand history; bankroll, reads and leaks are backed up first) |
+| `--no-browser` | don't open a browser |
+| `--no-coach` | don't run the built-in coach (if you run your own worker) |
+| `--host <ip>` | bind a Tailscale IP to play from another device |
+
+## Playing from a tablet
+
+The server is single-player with no auth, so where it binds *is* the security boundary. It only allows loopback or a Tailscale address (`100.64.0.0/10`); wildcard, public and LAN binds are refused, with anti-CSRF and DNS-rebinding guards on top.
+
+```bash
+gutcheck --host <this machine's tailscale IP> --no-browser
+# then open http://<that IP>:8777 on the iPad
+```
+
+Don't put it on the open internet. It has no login, by design.
+
+## Development
+
+```bash
+git clone https://github.com/phillipclapham/gutcheck
+cd gutcheck
+python3 -m venv venv && source venv/bin/activate
+pip install -e ".[mcp,anneal]" pytest
+GUTCHECK_DATA_DIR="$(mktemp -d)" python -m pytest -q
+```
+
+Always point tests and smoke runs at a throwaway data dir, or they'll play hands against your real bankroll.
+
+The package is `gutcheck/`: `server.py` (HTTP), `game.py` (the table), `engine.py` and `archetypes.py` (the hand engine and bot styles), `equity.py` and `ranges.py` (the equity oracle and the villain range model), `coach*.py` (the coach channel and workers), `leakstore.py` (leak memory), `mcp_server.py`, and `static/index.html` with `doctrine.md` (the table UI and the coaching doctrine). The doctrine is a plain markdown file, so you can read exactly what the coach is told.
+
+Python 3.11+. The only required dependency is [pokerkit](https://pypi.org/project/pokerkit/).
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

gutcheck-0.1.0/README.md

@@ -0,0 +1,135 @@
+# gutcheck
+
+**A poker reading trainer.**
+
+![Log a read, commit it, see the real number](https://raw.githubusercontent.com/phillipclapham/gutcheck/main/docs/gutcheck-loop.gif)
+
+You sit at a 6-max no-limit cash table against five bots. Each one plays a real, exploitable style: the rock, the reg, the calling station. The catch is that their names get shuffled against their styles every session, so you can't memorize who's who. You have to read them from how they play.
+
+Then, when it's your turn, you commit a read. How strong am I here? Is that guy actually on something? The trainer locks in what your gut said and shows you the real number, computed in code, never guessed. You see the gap. Do that a few hundred times and your feel for a table starts to line up with what's actually true.
+
+No account, no API key, no LLM needed. The bots are code and the equity math is exact. There's an optional AI coach if you want someone to talk the spot through with you, but the training loop never depends on it.
+
+```bash
+pip install gutcheck
+gutcheck
+```
+
+That opens a table in your browser at `http://127.0.0.1:8777`. Everything runs on your machine.
+
+## Play with Claude in the room
+
+This is how I actually use it. Start `gutcheck`, then open a Claude Code session with the gutcheck MCP server added (`pip install "gutcheck[mcp]"`, then `claude mcp add gutcheck -- gutcheck-mcp`, once). Now Claude can see the table you're sitting at, your hand history and your read stats, and you just talk it out while you play. What do you make of the guy who keeps check-raising? Was that fold as bad as it felt? Where are my reads drifting?
+
+It answers from what's actually on the table and in your history, not from vibes. And it only knows what you could know: the bots' hidden styles stay hidden, and it never sees their cards mid-hand, so it can't read them for you. It has to read them with you. It can't play your hands either. The clicking stays yours.
+
+## Why this exists
+
+I play by feel. Most of what happens at a poker table happens faster than I can do math, and I've always thought that was fine, since the gut is doing real work. But a gut that never gets checked isn't a skill. It's a mood.
+
+Solvers tell you the right play. They don't tell you how far off your read was, and that's the part I actually wanted to train. So gutcheck is built around one loop: **predict, check against ground truth, notice the gap, go again.** You commit before you see the answer, every time, so you can't fudge it after the fact.
+
+That loop isn't really about poker. It's the same thing whether you're reading a table, a codebase, or a room: say what you think is true, check it against something that can't lie to you, keep score. Poker just makes the scoring cheap and the ground truth exact.
+
+## How you train
+
+1. **Sit down.** A buy-in comes off your play-money bankroll and you get a fresh table.
+2. **Play.** Click any player to see what you've *observed* (VPIP, aggression, showdowns), never their hidden type. Guess it. There's a reveal button for checking yourself.
+3. **Log a read.** On your turn, hit **Log read ♠**. Set your gut equity on a slider in plain language ("behind", "a coin flip", "a favorite"), pick your lean, add a note if you want. Then the trainer shows you the modeled equity and names the gap.
+4. **Review.** After a hand, **⟳ review** replays it and stops at each of your decisions. Commit your gut again, then see the *exact* equity with every runout enumerated against the cards they really held.
+5. **Get up.** Cash out. A session report records your results, your biggest pots, and how your reads graded out per villain.
+
+Equity shows up as a felt band first ("a favorite") and the percentage second. The point is to train the feel, not to turn you into a calculator.
+
+Over time the **🎯 Reads** view tracks your calibration: all-time accuracy, the recent arc, and whether you're sharpening or drifting.
+
+## The optional coach
+
+When you want the *why*, hit **talk it through ♠** after a read and a coach walks through the spot, using the same number you just saw.
+
+Out of the box the coach tries the `claude` CLI if you have it (it rides your own Claude subscription). If it can't reach anything, it falls back to a plain facts readout: your equity band, the pot odds, what you've observed about each player. That always works, and the startup line tells you which one you're getting.
+
+Worth knowing: the `claude` provider runs a normal `claude -p` call, so your own `~/.claude/CLAUDE.md` loads with it. If that file says who you are, the coach knows you. It also means the spot you're asking about goes to whichever provider you picked, same as anything else you'd send it.
+
+Open **⚙ Settings** to pick a different provider:
+
+| Provider | What you need |
+|---|---|
+| Claude (default) | the `claude` CLI (Claude Code), logged in |
+| Codex | the `codex` CLI, logged in |
+| Anthropic API | `pip install "gutcheck[api]"` and your own API key |
+| OpenAI API | `pip install "gutcheck[api]"` and your own API key |
+
+API keys are stored locally in a file only you can read (`0600`) and never go back out through the settings API. Coaching can be switched off entirely in Settings if you'd rather just see the facts.
+
+**Leak memory.** With `pip install "gutcheck[anneal]"`, the coach also keeps a memory of your recurring mistakes. When the same misread shows up enough times, it gets a name ("fold reads undercount own equity"), cited back to the exact hands, and it graduates as it keeps happening. Next time you're in that spot, the coach brings it up. It's built on [anneal-memory](https://pypi.org/project/anneal-memory/).
+
+## Use it from Claude or another MCP client
+
+`pip install "gutcheck[mcp]"` adds `gutcheck-mcp`, an MCP server that lets an AI client read your table, your hand history and your calibration, and coach from them. It's read-mostly on purpose: the coach can see what you've observed, not the bots' hidden types, so it can't cheat for you.
+
+Start `gutcheck` first (the MCP server talks to it on port 8777), then register the MCP server. For Claude Code:
+
+```bash
+claude mcp add gutcheck -- gutcheck-mcp
+```
+
+For Claude Desktop or any other client, add a stdio server whose command is `gutcheck-mcp`.
+
+## Where your data lives
+
+```
+~/.gutcheck/
+    career.json          bankroll + lifetime stats
+    session.json         the table you're sitting at
+    sessions/<id>.json   session reports
+    calibration.json     your read accuracy over time
+    history.db           every hand you've played
+    coach.db             the local coach channel
+    settings.json        your settings
+    secrets.json         API keys, if you add any (0600)
+    leaks.db             leak memory, with the [anneal] extra
+```
+
+Set `GUTCHECK_DATA_DIR` to put it somewhere else. `gutcheck --reset` starts you fresh: it deletes the hand history, session reports and the current table, and keeps a one-step backup of your bankroll, read accuracy and leak memory in case you didn't mean it.
+
+## Flags
+
+| Flag | Does |
+|---|---|
+| `--port 8777` | change the port |
+| `--reset` | fresh start (deletes hand history; bankroll, reads and leaks are backed up first) |
+| `--no-browser` | don't open a browser |
+| `--no-coach` | don't run the built-in coach (if you run your own worker) |
+| `--host <ip>` | bind a Tailscale IP to play from another device |
+
+## Playing from a tablet
+
+The server is single-player with no auth, so where it binds *is* the security boundary. It only allows loopback or a Tailscale address (`100.64.0.0/10`); wildcard, public and LAN binds are refused, with anti-CSRF and DNS-rebinding guards on top.
+
+```bash
+gutcheck --host <this machine's tailscale IP> --no-browser
+# then open http://<that IP>:8777 on the iPad
+```
+
+Don't put it on the open internet. It has no login, by design.
+
+## Development
+
+```bash
+git clone https://github.com/phillipclapham/gutcheck
+cd gutcheck
+python3 -m venv venv && source venv/bin/activate
+pip install -e ".[mcp,anneal]" pytest
+GUTCHECK_DATA_DIR="$(mktemp -d)" python -m pytest -q
+```
+
+Always point tests and smoke runs at a throwaway data dir, or they'll play hands against your real bankroll.
+
+The package is `gutcheck/`: `server.py` (HTTP), `game.py` (the table), `engine.py` and `archetypes.py` (the hand engine and bot styles), `equity.py` and `ranges.py` (the equity oracle and the villain range model), `coach*.py` (the coach channel and workers), `leakstore.py` (leak memory), `mcp_server.py`, and `static/index.html` with `doctrine.md` (the table UI and the coaching doctrine). The doctrine is a plain markdown file, so you can read exactly what the coach is told.
+
+Python 3.11+. The only required dependency is [pokerkit](https://pypi.org/project/pokerkit/).
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

gutcheck-0.1.0/gutcheck/__init__.py

@@ -0,0 +1,13 @@
+"""gutcheck — a felt-sense poker reading-trainer.
+
+The importable package: the game engine, the local web table server, the MCP coach
+proxy, and the operator-owned graduating-leak store. Submodules are imported lazily by
+their consumers (``from gutcheck import server`` / ``from gutcheck.seam import Seam``);
+this ``__init__`` deliberately imports nothing so a plain ``import gutcheck`` has no
+side effects and can't trip the server→coach_daemon→… chain at package-load time.
+
+All runtime state lives OUTSIDE the package, under ``~/.gutcheck`` (override with
+``GUTCHECK_DATA_DIR``) — see ``gutcheck.paths`` — so a read-only wheel install is safe.
+"""
+
+__version__ = "0.1.0"