# Opening Cogdraft the first time

This note is for Cogdraft 1.1.0.

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.1.0-mac-arm64.zip` and `Cogdraft-1.1.0-mac-x64.zip`. Each zip contains `Cogdraft.app` only. The Windows download is the installer `Cogdraft-1.1.0-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.1.0-mac-arm64.zip`. The zip contains `Cogdraft.app` only. Move that app where you want it. The Intel zip is `Cogdraft-1.1.0-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.1.0-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 because it is not Authenticode signed. 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.

## 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`.
