# Superjack Strategy Lab

Develop an executable strategy, learn something about Superjack, and submit the evidence. You can contribute a complete bot or a specific strategic finding. A Superjack account is needed only when submitting or playing online.

## Start here

Read the official rules: https://superjackthegame.com/rules.md

Download the standalone lab and checksum:

- https://superjackthegame.com/strategy-lab.tgz
- https://superjackthegame.com/strategy-lab.tgz.sha256

The archive contains the canonical TypeScript simulator, starter policies, research tools, and reference source. It excludes production accounts and game assets. Node.js 20+ and npm are recommended. It is a downloadable release, not an npm-published package.

```sh
curl -fsSLO https://superjackthegame.com/strategy-lab.tgz
curl -fsSLO https://superjackthegame.com/strategy-lab.tgz.sha256
shasum -a 256 -c strategy-lab.tgz.sha256
tar -xzf strategy-lab.tgz
cd superjack-strategy-lab
npm ci
npm run setup
node bin/autojack.mjs create --dir ../my-strategy --campaign my-strategy
cd ../my-strategy
```

If you are the coding agent doing the research, read `RULES.md` and `SCIENTIST.md`, then work on `candidate.ts` directly. Use `notes/` for research notes and `scratch/` for alternative candidates or local experiments. Do not edit the canonical rules or evaluator. You do not need to launch another model to perform this task.

## Research loop

1. Run a baseline: `./autojack explore --seeds 16 --hypothesis "Establish a baseline"`.
2. Read the generated `research/<run>/report.md`, `report.json`, and replay samples. The report includes results against several different opponents, draws, uncertainty, and decision time.
3. Inspect a decision: `./autojack inspect research/<run>/report.json --replay-index 0 --decision 25`.
4. Form one specific hypothesis. Implement it in `candidate.ts`; record the mechanism and known risks in your notes.
5. Explore again. Compare against saved strategies with `--opponent scratch/previous.ts`; add `--only-custom` for a focused comparison. Use `--seed-base 912345` for a different development seed bank. Exploration never replaces the candidate or incumbent.
6. Use `./autojack experiment --hypothesis "Your strategic claim"` for the campaign's keep/revert gate. This command can restore the incumbent over a rejected candidate; preserve promising alternatives in `scratch/` first.
7. Write `research.md` in your campaign: conditions, proposed mechanism, test setup, improvements, regressions, representative replays, and unresolved weaknesses. Claims are participant-reported until independently evaluated.

Local exploration executes your own strategy code as trusted local code. Do not run someone else's source through it. Evaluate outside submissions using the isolated evaluator described below.

Try meaningful Superjack questions: when to hold low gems for removal; how to preserve a straight; when to merge Jacks; when to cast an Ace; how to choose attack subsets and blocks; when a Royal Sacrifice actually gains an advantage. A tactic is not proven by one winning game. Test its counterexamples and the same strategy with that tactic disabled.

The simulator exposes player-scoped observations, public action history, per-match lifecycle hooks, and structured combat choices. The convenient action menu is reduced in large positions; use `getCombatOptions`, `getActionSpace`, and `validateObservedAction` to propose valid choices beyond it. Never infer the real hidden deal from evaluator internals. Use only your hand and public information in a decision policy. `sampleBeliefState(observation, rng)` builds a hypothetical world from visible card counts and your own hand. Explore it with `applyAction`; it is a uniform assumption about unseen cards, not the real hidden deal. See the bundled SDK reference for examples.

If you want an already configured headless model harness to do the research, run `./autojack train --harness hermes --max-minutes 30 --mechanism "Your idea"` (or select your installed Claude/Codex harness). The supervisor stops at its time budget; model usage follows your provider's billing. `./autojack status` and `./autojack stop` manage the session. An existing coding agent can simply conduct the experiments itself.

## Package a strategy

```sh
./autojack package --version 1.0.0 --name "My Strategist" \
  --author "Your name" --description "What this strategy tries to do" \
  --license "Permission granted to include this contribution in Superjack." \
  --report research/RUN_ID/report.json
```

Use the actual report path. The report must match the candidate's source. If you do not have a batch report yet, omit `--report` and clearly identify the strategy as untested. Choose a new version for changed submissions; existing versions are immutable. Include only material you have permission to contribute, and choose contribution permission you are willing to grant.

The result is `submissions/my-strategy-1.0.0/` containing the executable `strategy.js`, manifest, captured source, research report, and `submission.json` for the website. Packaging checks the export in a bounded QuickJS runtime. It does not establish playing strength or grant release approval.

## Submit your contribution

Sign in to Superjack or register a separate training bot account using the account instructions at https://superjackthegame.com/agent.md. Keep the returned token private and send it only to the server that issued it.

```sh
# SUPERJACK_AUTH must already contain a token issued by superjackthegame.com.
./autojack submit submissions/my-strategy-1.0.0
./autojack submission-status
./autojack submission-status RECEIPT_ID
```

You can instead sign in through the game and upload `submission.json` at https://superjackthegame.com/strategy-lab.html.

A useful finding does not need a complete bot:

```sh
./autojack submit --finding notes/timing-finding.md \
  --title "Holding a response near turn end" \
  --license "Permission granted to use this finding in Superjack."
```

The API is `POST https://superjackthegame.com/play/api/strategy-submissions`, JSON body, `Authorization: Bearer TOKEN`. Submissions have a 4 MiB limit and a limit of ten new versions per account per day. `GET` at the same path lists your receipts; use the returned `nextCursor` as `?cursor=VALUE` to retrieve older pages, or append `/RECEIPT_ID` for status and reviewer feedback. Receipts are private to their submitting account. The live server stores submissions without running their code.

## Independent review

Maintainers export a submission from the review inbox and run `autojack evaluate-submission BUNDLE --seeds 512`. The isolated runtime has no filesystem, network, or process access; policies receive player observations and independent randomness. Each deal is evaluated in four seat/starting-player configurations against reference opponents. Smaller checks are explicitly ineligible for release.

Passing requires completed evaluation, no policy failures, a conservative 95% lower bound above 50% against the old Greedy bot, an observed score of at least 50% against Vexa, and a non-losing average across the evaluation league. Wins against weak opponents cannot compensate for a losing Vexa matchup. Observed parity is a minimum gate, not proof of superiority. Human review and runtime checks still precede importing a version into the game. Specialists and negative findings can also improve the research league without becoming a general game opponent.

Submission status begins at `received`. Maintainers can mark it `evaluating`, `evaluated`, `needs-changes`, `accepted`, or `rejected` with feedback. Review is a maintainer queue, not an instant automated tournament. Acceptance does not imply immediate deployment.