@xgamesfun/solana 0.0.0-stage → 0.20.1

package/DISCLAIMER.md

@@ -0,0 +1,41 @@
+# Disclaimer
+
+Read this before you use this package, its tools or the loot program. Using them means you accept it.
+
+## No warranty, use at your own risk
+
+- This package (`@xgamesfun/solana`, its CLI, MCP server, skill and plugin) and the loot program are provided **"as
+  is" and "as available"**, without warranties of any kind, express or implied, including merchantability, fitness
+  for a particular purpose, title and non-infringement. The [license](LICENSE) (Apache-2.0, sections 7 and 8) applies
+  in full.
+- **The loot program has not been independently audited.** It may contain bugs or vulnerabilities. We make no
+  guarantee that it, or anything this package builds, sends or signs for, is safe, secure, correct or available.
+  Tokens, NFTs and SOL sent to it can be lost, locked or taken, permanently.
+- Blockchain transactions cannot be undone. You are responsible for every transaction you approve, for your wallet
+  and its keys, and for checking what you sign.
+- The numbers the tools give (simulations, costs, odds, how long a pool lasts) are estimates from the spec and its
+  assumptions, not promises of what will happen.
+- The package relies on services nobody here controls: Solana itself and its RPC providers, the randomness oracle,
+  wallets, token and NFT programs, npm and any results server. Any of them can fail, change or stop.
+- The public results server (`https://play.xgames.fun/xsolana`) is offered as is, may change or stop at any time, and
+  carries no promise of uptime or of what it vouches for.
+- **Devnet only.** Nothing here is meant for real money until the program has been independently audited.
+
+## Use it legally
+
+- **Nothing here is legal, financial, tax or investment advice.** The legal flags the checker raises (chance at
+  money, resellable random items, revenue sharing, shill bidding) are reminders, not a complete list and not a legal
+  opinion. A spec with no flag is not therefore legal.
+- **You are solely responsible for making sure what you build, and how you run it, is legal everywhere it is
+  offered.** Depending on where you and your players are, that may include laws on gambling, lotteries, sweepstakes
+  and prize promotions, securities and commodities, money transmission and payments, consumer protection and odds
+  disclosure, age limits and children's privacy, data protection, tax, sanctions and anti-money-laundering.
+- Do not use this package or the program for anything unlawful, to evade sanctions, or where it is prohibited. Ask a
+  qualified lawyer before you offer anything with real value.
+
+## Limitation of liability
+
+To the fullest extent the law allows, games.fun, XGamesFun and the contributors to this package are not liable for any
+loss or damage of any kind, direct or indirect, including lost funds, tokens, NFTs, profits or data, arising from the
+use of, or inability to use, this package, the loot program, the results server or anything built with them, even if
+told such loss was possible.

package/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.

package/NOTICE

@@ -0,0 +1,13 @@
+loot
+Copyright 2026 games.fun
+
+This product includes software developed at games.fun.
+
+Parts of the JavaScript client and tools (js/) are adapted from the games.fun kit,
+MIT License, Copyright (c) 2026 games.fun.
+
+The tests run upstream Solana programs (SPL Token, Token-2022, Associated Token, Memo,
+Metaplex Core, Token Metadata, Bubblegum, Account Compression, Noop, MagicBlock VRF) as
+the clusters run them. Those binaries are downloaded by scripts/fetch-fixtures.mjs, checked
+against the hashes in js/test/fixtures/pinned.txt, and are not part of this repository or
+of the npm package. Each is licensed by its own authors.

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# solana-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The tools for **loot**, one shared Solana program for game and community economies. This repository is the npm
+package `@xgamesfun/solana`:
+
+- a JavaScript client with no Solana SDK (`@xgamesfun/solana/client`), a player module for apps (`/play`) and a results
+  client (`/results`);
+- the economy spec and its checker, quick simulation, cost and plain-words explainer;
+- the `xsolana` CLI and an MCP server with ten `xsolana_*` tools;
+- the `xsolana-economy` skill, and one plugin that carries the tools and the skill to Claude Code and Codex;
+- a local approval page where a project's owner approves going live in their own wallet.
+
+An economy is a JSON spec, not a new smart contract. Every project shares the one program, and none writes its own.
+
+> **Status:** loot 0.20.1, program ID `9cwqM1TXytPnFZsLfmUyv2dg4uW6Ch9C6UJVPns7NFQ`, **devnet only**. The program is
+> not independently audited, and nothing runs on mainnet until it is. See [SECURITY.md](SECURITY.md).
+
+> **Disclaimer:** provided as is, with no warranty and no guarantee that the program or the tools are safe. Use them
+> at your own risk; you are responsible for every transaction you approve and for making sure what you build is legal
+> where it runs. Nothing here is legal or financial advice. Read [DISCLAIMER.md](DISCLAIMER.md) before you use it.
+
+## What an economy can be made of
+
+- payments and splits, in tokens or with an NFT
+- shops (a purchase in one transaction) and loot boxes
+- pools and timed schedules, sealed or not
+- lotteries and raffles, including no-loss lotteries
+- prizes of any kind on every route, random or not: items, tokens, and NFTs the project holds in a stash
+- an NFT as the price on every route that takes money
+- staking farms with lock tiers, boosts, early exits and tolls
+- crafting recipes
+- holds and contests, with prizes by rank or by stake
+- auctions: the highest bid wins, the outbid refunded at once
+- listings for sale or rent, and bids and loans between players
+- perks, staking and holds for any NFT, whether the project has authority over it or not
+- allowlists of any size (a Merkle list) on every gated route
+- capped rewards and grants that a server vouches for
+- rules on what a collectible says
+
+Every move leaves a public receipt. [`docs/program.md`](docs/program.md) describes how the program behaves.
+
+## Use it from an AI coding agent
+
+The MCP server and the skill let Claude Code, Codex or any MCP agent turn a one-line idea into a checked, simulated
+economy and hand you the command that puts it live in your own wallet.
+
+**Claude Code**
+
+```
+/plugin marketplace add XGamesFun/solana-kit
+/plugin install xsolana@xgamesfun
+```
+
+**Codex**
+
+```
+codex plugin marketplace add XGamesFun/solana-kit
+codex plugin add xsolana@xgamesfun
+```
+
+**Any agent with MCP** (Cursor, opencode, Cline…): run the server with
+`npx -y --package=@xgamesfun/solana@0.20.1 xsolana mcp`. Or let `npx -y @xgamesfun/solana@0.20.1 connect` register it, with
+the skill, for Claude Code and Codex.
+
+Then ask for an economy, for example *"a fishing game where each cast costs 0.02 SOL, with a rare golden fish and a
+monthly draw"*.
+
+Going live is always yours: `npx -y @xgamesfun/solana@0.20.1 approve` opens a page on your computer where you connect a
+devnet wallet and approve each transaction. The agent never signs and never asks for a key.
+
+## Use it from a terminal
+
+Every tool runs from the CLI too, on a spec file (`xsolana.json` by default):
+
+```bash
+npx -y @xgamesfun/solana@0.20.1 examples shop with loot boxes   # the nearest worked examples
+npx -y @xgamesfun/solana@0.20.1 check xsolana.json                 # refusals and warnings
+npx -y @xgamesfun/solana@0.20.1 simulate xsolana.json              # where the money goes, day by day
+npx -y @xgamesfun/solana@0.20.1 cost xsolana.json                  # what going live and each action cost
+npx -y @xgamesfun/solana@0.20.1 explain xsolana.json               # the economy in plain words
+npx -y @xgamesfun/solana@0.20.1 approve xsolana.json               # go live, approved in your own wallet
+```
+
+`xsolana help` lists every command. Every command names the exact version, so `npx` runs that release and never whatever
+is newest under the name.
+
+## Use it from code
+
+```bash
+npm install @xgamesfun/solana
+```
+
+```js
+import * as loot from '@xgamesfun/solana/client';
+const ix = loot.openBoxIx({ player, project, box, nonce }); // one builder per instruction, no Solana SDK
+```
+
+| Import | What |
+| --- | --- |
+| `@xgamesfun/solana` | the economy tools: `check`, `simulate`, `plan`, `cost`, `explainEconomy`, `model` |
+| `@xgamesfun/solana/client` | every PDA, one builder per instruction, account and receipt decoders, grant vouchers |
+| `@xgamesfun/solana/play` | `solanaApp`: what a player does with a live economy, from a browser app |
+| `@xgamesfun/solana/results` | results and vouchers a game's server signs |
+| `@xgamesfun/solana/chain/*` | browser-safe Solana primitives: base58, Borsh, transactions, PDAs, tokens, Core |
+| `@xgamesfun/solana/idl.json` | the program's IDL, the authority for account and argument layouts |
+| `@xgamesfun/solana/release.json` | the program build, IDL and client this release is pinned to |
+
+The client, chain and play modules run in browsers and Node 22 or later, with no bundler required. The package
+ships TypeScript declarations for every entry point.
+
+## Documentation
+
+| | |
+| --- | --- |
+| [`docs/program.md`](docs/program.md) | the program: who signs, accounts, every instruction, fees, limits, receipts, costs |
+| [`docs/nfts.md`](docs/nfts.md) | NFTs and tokens, with and without the project's authority |
+| [`docs/harnesses.md`](docs/harnesses.md) | how the plugin reaches Claude Code and Codex, and the release checklist |
+| [`skills/xsolana-economy`](skills/xsolana-economy/SKILL.md) | the skill an agent follows |
+| [`examples/`](examples) | whole economies that check and go live in the tests; `ideas.json`, 112 real economies rated |
+| [`evals/`](evals/README.md) | fresh-session evals of agents building on loot |
+| [`CHANGELOG.md`](CHANGELOG.md), [`SECURITY.md`](SECURITY.md) | versions, the trust model, reporting a vulnerability |
+
+## Layout
+
+| Path | What |
+| --- | --- |
+| `js/chain/` | browser-safe Solana primitives, no SDK |
+| `js/client/` | the client; `idl/` is the program's IDL |
+| `js/economy/` | the economy spec (version 2, `schema.json`), checker, simulation, setup plan, cost, explainer, guide |
+| `js/play/`, `js/results/` | a player's side of a live economy; results a server vouches for |
+| `js/approve/`, `js/mcp/`, `js/connect/` | the approval page, the MCP server and its tools, `xsolana connect` |
+| `js/sim/`, `js/test/` | LiteSVM running the real program; the tests and their pinned fixtures |
+| `bin/xsolana.mjs` | the CLI |
+| `skills/`, `plugin/` | the skill (copied to `plugin/skills`, `.claude/skills`, `.agents/skills`) and the plugin |
+| `scripts/` | fixtures, skill sync, IDL sync, release manifest, a devnet end-to-end run |
+| `release.json` | the program binary, IDL and client hashes this version is pinned to |
+
+## Development
+
+Node 22 or later.
+
+```bash
+npm ci
+npm run fixtures   # downloads the loot program from devnet and the programs it calls from mainnet, each checked by hash
+npm test           # every instruction the client builds, and every example's whole setup, against the real program in LiteSVM
+npm run lint       # ESLint
+npm run check      # fixtures, skill copies and release.json in step, lint, then the tests
+```
+
+Nothing in the tests deploys or spends SOL.
+
+| Variable | What it does |
+| --- | --- |
+| `XSOLANA_RPC_URL` | a devnet RPC of your own for `xsolana approve` and `xsolana status` (a mainnet URL is refused) |
+| `XSOLANA_NO_OPEN` | `xsolana approve` prints its link without opening a browser |
+| `XSOLANA_DEBUG` | the CLI prints a failure's whole stack, not one line |
+| `XSOLANA_PROGRAM_DIR` | the tests run that program build's `target/deploy/loot.so`, and check the IDL against it | To try the tools in your own agent from a clone,
+`node bin/xsolana.mjs connect --local` registers this checkout's MCP server and the skill with Claude Code and Codex
+(`--remove` takes them out again).
+
+After editing `skills/`, run `npm run sync-skills`. Changes to tool texts, the skill or the plugin are best measured
+with the evals before and after ([`evals/README.md`](evals/README.md)). [`AGENTS.md`](AGENTS.md) has the rules for
+working in this repository, for people and coding agents alike.
+
+## Contributing
+
+Issues and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Please run `npm run check` before
+sending a change, and report a vulnerability privately as [SECURITY.md](SECURITY.md) describes.
+
+## License
+
+[Apache-2.0](LICENSE). See [NOTICE](NOTICE) and [DISCLAIMER.md](DISCLAIMER.md): provided as is, without warranty, at your
+own risk.

package/bin/xsolana.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// xsolana: the command line of @xgamesfun/solana. Every tool the MCP server has runs here too, with the same arguments and
+// the same answer, for an agent (or a person) without MCP.
+//
+//   xsolana mcp                          serve the tools over stdio (what a plugin's MCP config runs)
+//   xsolana guide [part] [--json]        what an economy can be made of, and what loot cannot do
+//   xsolana examples [words…] [--json]   the nearest worked examples and rated economies
+//   xsolana check|simulate|cost|explain|publish|status [file] [--json]   one tool on a spec file (default xsolana.json)
+//   xsolana approve [file] [--port n] [--no-open]   open the local page where the owner approves going live in their wallet
+//   xsolana connect [--agent claude|codex] [--scope user|project] [--local] [--remove] [--dry-run]   register the MCP server and the skill
+//   xsolana tool --list | xsolana tool <name> '<json>' [--args-file f] [--json]   any tool by name
+//   xsolana version
+//
+// A flag with a value is written either way: --agent claude or --agent=claude; a flag the command doesn't take is
+// refused. A command that fails says why on stderr and exits 1: a usage error in one line (XSOLANA_DEBUG=1 prints the
+// whole stack), a tool's refusal with the tool's own answer. `--json` prints a tool's whole answer on stdout, whatever
+// it is, and the exit code still says whether it failed.
+import { readFile } from 'node:fs/promises';
+
+const USAGE = `xsolana: the tools for loot, one shared Solana program for game and community economies.
+
+  xsolana guide [part]            what an economy can be made of
+  xsolana examples [words…]       where to start
+  xsolana check [file]            refusals and warnings (default xsolana.json)
+  xsolana simulate [file]         the quick simulation
+  xsolana cost [file]             what going live and each action cost
+  xsolana explain [file]          the economy in plain words
+  xsolana publish [file]          what going live does, and how to approve it
+  xsolana approve [file]          approve going live in your own wallet (a local page; --port n, --no-open)
+  xsolana status [file]           a live economy on chain
+  xsolana connect                 add the xsolana tools to Claude Code or Codex (--agent claude|codex, --scope user|project, --local, --remove, --dry-run)
+  xsolana mcp                     serve the tools over MCP (stdio)
+  xsolana tool --list             every tool; xsolana tool <name> '<json>' runs one (--args-file f)
+  xsolana version                 this package's xsolana version and program
+
+  A tool's command (guide, examples, check … status, tool) takes --json for its whole answer as JSON.`;
+
+/** A failure the person caused (a bad flag, a missing file): said in one line, without a stack. */
+class UsageError extends Error {}
+
+/** The flags that take a value: `--name value` or `--name=value`. */
+const VALUED = new Set(['--args-file', '--agent', '--scope', '--port']);
+/** The flags each command takes; any other is refused. */
+const TOOL_FLAGS = ['--json'];
+const FLAGS = {
+  mcp: [],
+  guide: TOOL_FLAGS,
+  examples: TOOL_FLAGS,
+  check: TOOL_FLAGS,
+  simulate: TOOL_FLAGS,
+  cost: TOOL_FLAGS,
+  explain: TOOL_FLAGS,
+  publish: TOOL_FLAGS,
+  status: TOOL_FLAGS,
+  approve: ['--port', '--no-open'],
+  connect: ['--agent', '--scope', '--local', '--remove', '--dry-run'],
+  tool: ['--list', '--args-file', ...TOOL_FLAGS],
+  version: [],
+};
+
+/** The arguments after the command: { flags (every --name given), values (--name → value), positional }. */
+function parseArgs(rest) {
+  const flags = new Set();
+  const values = new Map();
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (!a.startsWith('--') || a === '--') {
+      positional.push(a);
+      continue;
+    }
+    const eq = a.indexOf('=');
+    const name = eq > 0 ? a.slice(0, eq) : a;
+    flags.add(name);
+    if (eq > 0) values.set(name, a.slice(eq + 1));
+    else if (VALUED.has(name)) {
+      if (i + 1 >= rest.length || rest[i + 1].startsWith('--')) throw new UsageError(`${name} needs a value (${name} <value> or ${name}=<value>).`);
+      values.set(name, rest[++i]);
+    }
+  }
+  return { flags, values, positional };
+}
+
+/** The port `xsolana approve` listens on: a whole number from 1 to 65535, or undefined for any free one. */
+function portOf(value) {
+  if (value === undefined) return undefined;
+  const n = Number(value);
+  if (!/^\d+$/.test(String(value)) || n < 1 || n > 65535) throw new UsageError(`--port must be a whole number from 1 to 65535, not ${JSON.stringify(value)}.`);
+  return n;
+}
+
+async function main(argv) {
+  const [command, ...rest] = argv;
+  const { flags, values, positional } = parseArgs(rest);
+  const takes = Object.hasOwn(FLAGS, command) ? FLAGS[command] : null;
+  const unknown = takes && [...flags].find((f) => !takes.includes(f));
+  if (unknown) throw new UsageError(`“${command}” takes no ${unknown} flag (${takes.length ? `only ${takes.join(', ')}` : 'it takes none'}).`);
+
+  async function tool(name, input) {
+    const { runTool } = await import('../js/mcp/server.mjs');
+    const r = await runTool(name, input, { cwd: process.cwd() });
+    const failed = Boolean(r.isError || r.ok === false);
+    if (flags.has('--json')) console.log(JSON.stringify(r, (_, v) => (typeof v === 'bigint' ? v.toString() : v), 2));
+    else (failed ? console.error : console.log)(r.text ?? JSON.stringify(r, null, 2));
+    if (failed) process.exitCode = 1;
+  }
+
+  const fileInput = () => (positional[0] ? { file: positional[0] } : {});
+
+  switch (command) {
+    case 'mcp': {
+      const { serveStdio } = await import('../js/mcp/server.mjs');
+      await serveStdio();
+      break;
+    }
+    case 'guide':
+      await tool('xsolana_guide', positional[0] ? { part: positional[0] } : {});
+      break;
+    case 'examples':
+      await tool('xsolana_examples', positional.length ? { query: positional.join(' ') } : {});
+      break;
+    case 'check':
+    case 'simulate':
+    case 'cost':
+    case 'explain':
+    case 'publish':
+    case 'status':
+      await tool(`xsolana_${command}`, fileInput());
+      break;
+    case 'approve': {
+      const port = portOf(values.get('--port'));
+      const { approve } = await import('../js/approve/server.mjs');
+      await approve({ file: positional[0] ?? 'xsolana.json', port, open: !flags.has('--no-open') });
+      break;
+    }
+    case 'connect': {
+      const { connect } = await import('../js/connect/connect.mjs');
+      process.exitCode = await connect({ agent: values.get('--agent'), local: flags.has('--local'), remove: flags.has('--remove'), dryRun: flags.has('--dry-run'), scope: values.get('--scope') });
+      break;
+    }
+    case 'tool': {
+      const { tools } = await import('../js/mcp/tools.mjs');
+      if (flags.has('--list') || !positional[0]) {
+        for (const t of tools) console.log(`${t.name}\n  ${t.description.split('. ')[0]}.`);
+        break;
+      }
+      const from = values.get('--args-file');
+      const raw = from ? await readFile(from, 'utf8') : positional[1] ?? '{}';
+      let input;
+      try {
+        input = JSON.parse(raw);
+      } catch (e) {
+        throw new UsageError(`The arguments ${from ? `in ${from} ` : ''}are not JSON (${e.message}). Give them as one word, as in: xsolana tool xsolana_check '{"file":"xsolana.json"}'.`, { cause: e });
+      }
+      await tool(positional[0], input);
+      break;
+    }
+    case 'version':
+    case '--version': {
+      const { VERSION, PROGRAM_INFO } = await import('../js/mcp/tools.mjs');
+      console.log(`@xgamesfun/solana · loot ${VERSION} · program ${PROGRAM_INFO.program} · ${PROGRAM_INFO.cluster}`);
+      break;
+    }
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(USAGE);
+      break;
+    default:
+      console.error(`xsolana: there is no command “${command}”.\n\n${USAGE}`);
+      process.exitCode = 1;
+  }
+}
+
+/** One line for a failure: what went wrong, without a stack (a missing file names the file). */
+function oneLine(e) {
+  if (e?.code === 'ENOENT' && e.path) return `${e.path} does not exist.`;
+  if (e?.code === 'EADDRINUSE') return `Port ${e.port} is in use: pick another with --port, or leave it out for any free one.`;
+  return String(e?.message ?? e);
+}
+
+try {
+  await main(process.argv.slice(2));
+} catch (e) {
+  if (process.env.XSOLANA_DEBUG) console.error(e);
+  else console.error(`xsolana: ${oneLine(e)}`);
+  process.exitCode = 1;
+}