# The Publish Flow

> What happens when you edit a mod in Edit Mode: the debounced auto-checkpoint, Publish, the wip-to-main merge, the generated repository README, and registration.

- Source: https://diceytable.com/docs/mods/publishing/publish-flow
- Last verified: 2026-09-29

Editing a mod in Edit Mode drives two distinct kinds of push to GitHub: a background
**checkpoint** that happens automatically while you work, and an explicit **publish**
that you trigger when the mod is ready for other people. Only one of the two makes the
mod playable in multiplayer.

## Checkpoints: your safety net, not your release

Every edit marks the draft dirty. Ten seconds after edits settle, the editor pushes a
checkpoint commit to the mod's `wip` branch — debounced so a burst of changes collapses
into one push rather than one per keystroke. If a checkpoint push fails (for example, a
transient conflict right after a publish touched the same branch), the editor retries
once, at three times the normal delay, without waiting for you to make another edit.

Checkpoints exist so your work is never sitting *only* in the browser. They are
intentionally **not** a release action: pushing to `wip` does not merge to `main` and
does not register the mod, so nothing you checkpoint is visible to other players until
you publish. See [wip and main](https://diceytable.com/docs/mods/publishing/wip-and-main) for the full
two-branch model, including why checkpoints only send the files that actually changed.

## The publish-readiness gate

Before the **Publish** button will do anything, the mod's manifest must satisfy the
same discovery requirements as the mods library: a title, a summary, a square cover
image, and at least one screenshot. If any are missing, Publish stays disabled and the
dialog lists exactly what to add in **Mod Details** (the manifest editor's **Details** tab).

## The version number

The Publish dialog has a **Version** field, filled in with whatever your manifest's
`version` currently says. It is semver — `1.0.0`, or `1.2.0-beta.1` — and the field
refuses anything else, because the manifest schema would too.

Editing it is a real edit, not a setting that only applies to this publish: when you
leave the field (or press Enter), the editor writes the new number into
`diceytable.mod.json`, saves the draft, and checkpoints it to `wip` straight away
rather than waiting for the usual ten-second debounce. Clicking **Publish** with a
number still being typed is safe — the publish waits for that save before it pushes
anything, so the tree it promotes always carries the version you can see.

**A published version is permanent.** Once a version has been published, it resolves to
one specific commit forever, and nothing you do later can repoint it — that is what
makes it safe for another pack to depend on yours. So the dialog asks the server, as
soon as you open it, what `main` already ships and what the registry already has a row
for. If the number in the field matches either, you get a warning under the field
telling you to bump it. Publish anyway and the server refuses the merge, before `main`
moves — but the warning is there so you find out while the field is still in front of
you.

Bumping the number clears the warning immediately; there is no need to wait for another
round trip.

## Credits an AI agent attested must be reviewed

If an AI agent answered the import credit question for any of your files, those credit records
are **unreviewed** until a person signs them, and no publish goes through while one is. This is
the one credit question that blocks a publish: files with no credit at all do not.

Review them first: tick each record you have checked and type your name, and each one is signed.
See [Credits an AI agent attested](https://diceytable.com/docs/mods/publishing/attribution#credits-an-ai-agent-attested)
for what you are signing, and [Mod Details: the Credits
tab](https://diceytable.com/docs/editor/interface/topbar#mod-details-the-credits-tab) for where.

If you publish with a record still unreviewed, the server refuses the merge **before `main`
moves**:

- **HTTP 409**, with `error: "ai-credits-unreviewed"` and `recordIds` listing the id of every record
  still waiting. The message names up to ten of them: *Review the credits an AI agent attested
  before publishing: open Manifest ▸ Credits (or the Publish dialog), check each record and sign
  it with your name, then publish again. … Nothing was published — the release branch is
  unchanged.*
- The work-branch push that came before it has already happened, so your edits are safe on
  `wip`. Only the release is refused.
- It applies to **every** publish, including a re-publish of a tree that has not changed.
- It fails closed. A record whose agent record or signature is malformed counts as unreviewed, and
  a record with no `id` is listed by its position (`credits[3]`).

Publishing some other way does not avoid it: the scanner refuses the same manifest at
registration with [`ai-credit-unreviewed`](https://diceytable.com/docs/mods/scanner/what-gets-rejected#ai-credit-unreviewed).

## What happens when you click Publish

Publishing is three steps, in order, and each one only runs if the previous one
succeeded:

1. **Push to `wip`.** Your current tree is compared file by file against what `wip`
   actually holds on GitHub, and every file whose content differs is committed. Because
   the comparison is against the branch itself rather than against earlier checkpoints,
   the branch that's about to become live cannot be missing an asset.
2. **Merge `wip` into `main`.** The server asks GitHub to merge the branch. If `main`
   was already up to date with `wip`, nothing changes and the dialog says so instead of
   claiming a fresh publish. If the merge can't fast-forward, you'll see a merge-conflict
   error — this can happen if you (or a collaborator) edited files on `main` directly on
   GitHub outside the editor. Before merging, the server checks what it can refuse up front
   (an [unreviewed AI-attested credit](https://diceytable.com/docs/mods/publishing/publish-flow#credits-an-ai-agent-attested-must-be-reviewed), a
   changed pack type, or a version already published at another commit) and answers 409
   without merging.
3. **Register (and re-scan) the mod.** The editor immediately calls mod registration
   against the just-merged `main` branch. This is what makes the mod appear, playable,
   in the mods library — see [Registration & Multiplayer Play](https://diceytable.com/docs/mods/publishing/registration-and-play)
   for what that unlocks and why it's required.

### Watching a publish

While a publish runs, the dialog shows a progress bar and a checklist of its phases,
with the running one marked:

1. **Save changes** — flushes open editor tabs and saves the draft.
2. **Compare with GitHub** — hashes each local file against what `wip` already holds
   (`12/40` counts the files checked). Only files whose content differs are sent.
3. **Upload files** — only for a publish too large for one request (over 24 MB once encoded)
   or with more than 40 changed files; files go up one at a time and the list shows each one
   as queued, sending or sent. Otherwise this phase is struck through as skipped.
4. **Commit to work branch** — the commit to `wip`, listing every file it adds, changes
   or deletes.
5. **Merge into release branch** — the `wip` → `main` merge, listing the files GitHub
   reports the merge changed (the first 200 on a very large merge).
6. **Register & scan** — including any "GitHub is still catching up" retries.

Click a finished phase to see its file list again. If a phase fails, it turns red and
shows the reason, and the bar stops where the publish did. Closing the dialog does not
cancel a publish; reopen it to keep watching.

If the push and merge succeed but registration fails (a network blip, a scanner
outage), the dialog tells you plainly: the mod **is** published to `main`, but you'll
need to add it manually from the mods library, because pushing files to GitHub alone
does not make a mod playable.

If registration succeeds but the scanner finds a problem with what you published, the
status line reports the scan status and the first compatibility issue rather than
silently claiming success — a mod can be pushed to `main` and still come back
`incompatible`. See the scanner reference under **Mod Files → Scanner** for what gets
rejected and why.

## Your repository page is generated too

Your mod's GitHub repository is a public page, and for most people it is the first one they
find. So every publish rewrites two things on it from your manifest, and keeps rewriting them
so they can never drift from what Mod Details says:

- **`README.md`** — the mod's name as the heading, then one sentence saying what kind of pack
  this is and that it runs on DiceyTable (linking the site), then a prominent link to your mod's
  own page — `/games/<slug>` for a game, `/mods/<slug>` for a table, room or asset pack — and
  then your description, exactly as you wrote it in Mod Details. Its markdown is passed through
  untouched, so lists, headings and links survive.
- **The repository's Website field** — pointed at that same mod page, so GitHub's own repo header
  links to it. This needs admin rights on the repository; if your account only has push access
  the publish still succeeds and the field is left alone.

Because these are regenerated, `README.md` is **read-only in the editor** and never takes part
in sync conflicts: change the description, the category, the pack type or the URL slug in
**Mod Details**, and the next publish carries all of it across. A publish that changes nothing
about them rewrites nothing — the file's content hash is unchanged, so it stays out of the
commit.

If your manifest doesn't parse, no README is generated and whatever the repository already has
is left alone; the scanner reports the manifest problem instead.

## After publishing

The published repository is remembered on the mod's project record, so the next time
you open it in the editor you don't need to re-link or re-type the repo. Closing **Mod
Details** after making changes also triggers a save-and-checkpoint automatically, so
you don't have to remember to hit Save before it's safe to walk away — but remember
that still only reaches `wip`. Nothing is live for other players until you publish.

## See also

- [wip and main](https://diceytable.com/docs/mods/publishing/wip-and-main)
- [Registration & Multiplayer Play](https://diceytable.com/docs/mods/publishing/registration-and-play)
- [Troubleshooting](https://diceytable.com/docs/mods/publishing/troubleshooting)
- [Required & conventional files](https://diceytable.com/docs/mods/files/required-and-conventional) — where the generated `README.md` sits in the tree
- [What gets rejected](https://diceytable.com/docs/mods/scanner/what-gets-rejected) — every rule the scan in this flow can fail on.
