# Opening Cogdraft the first time

This note is for Cogdraft 1.2.9.

macOS or Windows may block a copy that you have not approved. Do not clear the quarantine flag, and do not turn Gatekeeper, SmartScreen, Defender, or any other protection off. If the system does not offer a way to open the file, stop. In-app updates check an Ed25519 signature before they download.

The Mac downloads are complete files: `Cogdraft-1.2.9-mac-arm64.zip` and `Cogdraft-1.2.9-mac-x64.zip`. Each zip contains `Cogdraft.app` only. The Windows download is the installer `Cogdraft-1.2.9-win-x64.exe`. `SHA256SUMS.txt` lists the SHA-256 for each of those files. Check the file you downloaded against that list before you open it.

## macOS (Apple Silicon)

1. Unzip `Cogdraft-1.2.9-mac-arm64.zip`. The zip contains `Cogdraft.app` only. Move that app where you want it. The Intel zip is `Cogdraft-1.2.9-mac-x64.zip` and has the same layout.
2. Open `Cogdraft.app` only if macOS lets you open the file you checked. Do not clear quarantine.
3. The first window needs a moment while the local server starts. If it closes immediately, run the binary inside the app from Terminal to see the error:

```bash
Cogdraft.app/Contents/MacOS/Cogdraft
```

Cogdraft does not need an internet connection after you have the jars you want. The vanilla client download is optional and talks only to Mojang's version servers.

A second launch focuses the window that is already open. If port 43124 is taken, the app picks the next free port and writes it into the session file. You do not type the port into the window.

## Windows (64-bit)

1. Run `Cogdraft-1.2.9-win-x64.exe` only if Windows lets you open the file you checked. The default folder is `%LOCALAPPDATA%\Programs\Cogdraft`. Keep that folder together. `Cogdraft.exe` needs the `resources` directory beside it. `HOW-TO-OPEN.txt` is in that folder.
2. Windows may block or warn about this file. Do not turn SmartScreen, Defender, or any other protection off. If Windows does not offer a way to open the file, stop.
3. If you downloaded the installer in a browser, you can also right-click it, open Properties, and check Unblock before you run it.
4. The app listens only on `127.0.0.1`. Allow it if a firewall prompt appears. It does not need inbound access from other computers.

## After it opens

1. Settings, Download vanilla 1.21.1 client, or add your NeoForge and Create jars. Cogdraft reads blockstates, models, and textures from those jars. It does not ship Mojang's files. Jars you add are remembered and loaded again the next time the app starts.
2. Optional: load a registry dump JSON from Settings. The file looks like this:

```json
{
  "format": "cogdraft-registry",
  "format_version": 1,
  "blocks": [
    {
      "id": "create:belt",
      "properties": [
        {"name": "axis", "values": ["x", "z"], "default": "x"}
      ]
    },
    {"id": "minecraft:stone", "properties": []}
  ]
}
```

`format` must be `cogdraft-registry` and `format_version` must be `1`. Each block needs an `id`. `properties` may be omitted. Each property needs `name` and `values`. `default` is optional. This file is not a schematic.

3. Or click Load sample pack to place a few original sample blocks and see Create belt stand-ins. Chests and signs use the same kind of stand-in when the jar has no block model for them.
4. Copy the token from Settings into an AI client. The token stays the same across launches. It changes only when you click Generate new token. Update the client after you do that.

## The 3D view

The view keeps a full-detail window around the camera so a large build stays editable. The window is 256 blocks across by default. Settings can raise it to 512, 1024, or 2048 blocks across. Those larger windows are for a stronger computer. That choice is a warning, not a hard stop.

Show whole model frames the full build. The button is in the top bar, and the shortcut is H. Whole model detail defaults to Full, which draws every block with the real models, even past the window and the far budget. A large build shows a warning with a rough size first. That warning is not a hard stop. You can show the full detail anyway, or switch to Simple cubes. Simple cubes keeps full detail near the camera and draws the rest as colored cubes. Far cube in Settings is how many blocks those cubes merge. The choices are 4, 8, 16, 32, and 64, and the default is 8. Far budget is the most cubes to draw, and the default is 24000. The view uses a coarser cube until the count fits. Picking and editing use the full-detail blocks.

Picture saves a PNG of the current view. The shot leaves out the editor controls and the selection outline. Settings can turn each caption on or off. Build name, dimensions, block count, and the Cogdraft watermark start on. Date, block types, and the camera view start off.

These view settings stay on this computer. They are not part of the project file. A build longer than the window opens on the section around the camera until you show the whole model.

Home and F move the camera and keep the mesh that is already loaded. Reset view does the same.

Export Prep splits a build into pieces. Set a maximum width, height, and length, or add cut planes and drag them. Each piece is drawn with its own color and number. The list, the view, the file names, and the placement guide use that same number, along X, then Y, then Z. Offsets are never negative. Preview shows one piece, and Show all returns to the full layout. A picture taken during that preview uses the piece size and block count. The panel stays open after the pieces are saved, and the list then shows each file's real size. Part numbers use enough digits for the piece count. Create schematics (pieces) writes one .nbt file per piece and a placement guide. One .cogdraft file stores the whole build with no piece size cap. Piece size and the Create upload warning default to 64 blocks and 256 KB. Both can be changed in Settings. Picture file names include the time, so a second picture the same day does not ask to replace the first.

## AI clients

Open Cogdraft first so the session file exists. Then point the client at the sidecar with `--mcp-stdio`.

- macOS sidecar: `Cogdraft.app/Contents/Resources/sidecar/cogdraft-server`
- Windows sidecar: `%LOCALAPPDATA%\Programs\Cogdraft\resources\sidecar\cogdraft-server.exe`

The session file is `~/Library/Application Support/cogdraft/session.json` on macOS and `%APPDATA%\cogdraft\session.json` on Windows. It holds the port and the token. The stdio process reads that file and forwards JSON-RPC to the running app. If you set `COGDRAFT_TOKEN`, it must match the token in Settings.

Claude Desktop uses `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows:

```json
{
  "mcpServers": {
    "cogdraft": {
      "command": "/absolute/path/to/cogdraft-server",
      "args": ["--mcp-stdio"],
      "env": {
        "COGDRAFT_TOKEN": "paste-the-token-from-settings"
      }
    }
  }
}
```

Ollama does not speak MCP by itself. Use an MCP client that can also talk to Ollama, such as mcp-client-for-ollama (`uvx mcp-client-for-ollama`, or `ollmcp`), and give it the same command, args, and token.

`export` from a client must include a `path`. Cogdraft will not replace an existing file unless you also pass `"overwrite": true`.

## Create parts

Create's server rejects schematic uploads over 256 KB. Export, Create .nbt, with split enabled, writes `name_part01.nbt`, `name_part02.nbt`, and so on. Each part is a normal Create schematic. `CogdraftSplit.PartOffset` is that part's minimum corner relative to the original build origin, and `TotalSize` is the original volume. Place part 1 at the build origin, then place each later part at origin plus `PartOffset`.
