# Mock2 offline download and manual transfer

The source ZIP lets you carry a specific Mock2 standards release to a machine that cannot reach the Mock2 website or Git server. Download on a machine that can connect, copy the ZIP and its checksum to the destination, extract it separately from your application, and apply the standards from that local folder.

## Identify the package

The download section at <https://mock2.fractionate.ai/> links to the current package. The machine-readable download record is <https://mock2.fractionate.ai/downloads/latest.json>.

For this release:

| Item | Meaning |
| --- | --- |
| `mock2-core-1.40.0-<shortsha>.zip` | Source package; the filename includes the abbreviated source Git commit. Use the actual filename shown by the download record. |
| The same filename with `.sha256` appended | SHA-256 checksum of the complete ZIP. Carry this beside the ZIP. |
| `mock2-core-1.40.0/` | Top-level directory created by extraction. |
| `OFFLINE-PACKAGE.json` inside that directory | Package identity and the exact source Git commit used to build it. |
| `manifest.json` and `release.json` | Release metadata and the identities of published installer files. |
| `core/mock2/templates/repo/` | Payload for repository-local standards installation and upgrades. |
| `core/mock2/templates/repo/.mock2/template-manifest.json` | Version, ownership, and SHA-256 of each repository template file. |
| This `OFFLINE-INSTALL.md` | Transfer, installation, editor, and Git instructions. |

Keep the ZIP, checksum, and package metadata together when recording what was transferred. Compare the package version and source commit with the download record. A matching ZIP checksum checks that the transferred bytes match the published checksum; the local upgrader also verifies the template files before applying them.

This is a Mock2 standards source package. It does not include your application's source, database, uploaded files, secrets, installed dependencies, editor extensions, or Git history. It does not make an application install or deployment independent of its own dependencies. Follow that application's deployment procedure separately.

## Download and transfer

Download both the ZIP and its `.sha256` sidecar from the website on a connected computer. Use your normal file-transfer method, removable media, or an approved shared folder to copy both to the destination.

Choose a staging folder outside the application checkout, for example `~/mock2-transfer`. Do not extract over an existing application and do not replace its `.git` directory. Keep the extracted package in staging; the upgrader decides which files belong in the target repository.

If you use VS Code Remote SSH, the destination project and the extracted package must both exist on the remote host. A file downloaded onto your laptop is not automatically available to the remote terminal. Transfer the archive to the host, then verify and extract it there. Alternatively, transfer an already verified extracted directory while preserving all dotfiles and binary files, then let the upgrader verify the template hashes.

## Verify and extract on Linux

These commands run on the destination machine. Replace the archive filename with the exact filename you downloaded; `<shortsha>` is a placeholder, not literal text to type.

```bash
cd "$HOME/mock2-transfer"
archive='mock2-core-1.40.0-<shortsha>.zip'
sha256sum --check "$archive.sha256"
```

Stop if checksum verification fails. Extract only after it reports `OK`, into a new empty staging directory:

```bash
mkdir "$HOME/mock2-transfer/extracted-1.40.0"
unzip "$archive" -d "$HOME/mock2-transfer/extracted-1.40.0"
package="$HOME/mock2-transfer/extracted-1.40.0/mock2-core-1.40.0"
cat "$package/OFFLINE-PACKAGE.json"
```

On macOS, use `shasum -a 256 -c "$archive.sha256"` for the checksum step. An unzip utility must already be installed, or the ZIP can be extracted with your operating system's archive tool.

## Verify and extract with PowerShell

Run in PowerShell on the destination Windows machine. Set the filename to the actual download name first.

```powershell
Set-Location (Join-Path $HOME 'mock2-transfer')
$archive = 'mock2-core-1.40.0-<shortsha>.zip'
$expected = ((Get-Content -LiteralPath "$archive.sha256" -Raw).Trim() -split '\s+')[0]
$actual = (Get-FileHash -LiteralPath $archive -Algorithm SHA256).Hash
if ($expected -notmatch '^[0-9a-fA-F]{64}$' -or $actual -ine $expected) {
    throw 'ZIP checksum mismatch. Stop and transfer the package again.'
}
$staging = Join-Path $HOME 'mock2-transfer/extracted-1.40.0'
if (Test-Path -LiteralPath $staging) {
    throw 'Choose a new, empty extraction directory.'
}
Expand-Archive -LiteralPath $archive -DestinationPath $staging
$package = Join-Path $staging 'mock2-core-1.40.0'
Get-Content -LiteralPath (Join-Path $package 'OFFLINE-PACKAGE.json')
```

## Upgrade an existing application repository

Git and Node.js 18 or later must already be installed on the destination. The local-folder upgrade uses Node's built-in modules and requires no package installation or network connection. Confirm the prerequisites:

```text
git --version
node --version
```

First open the existing application checkout and inspect its state:

```text
git status
git branch --show-current
git remote -v
```

Start from the branch and commit you intend to update. Commit or deliberately stash your existing work, including any untracked files that matter. Finish or abort an active merge, rebase, cherry-pick, revert, or bisect before applying this update. Ensure Git has a configured name and email for its commit. Do not delete an index lock while another Git operation is running.

The following example creates a dedicated update branch from the current commit. If that branch name already exists, inspect and continue that branch or choose a new name; do not overwrite it.

```text
git switch -c mock2/standards-1.40.0
```

Use the upgrader from the extracted package so the operation uses the version you transferred. Its payload is the `core/mock2/templates/repo` directory, not the ZIP root.

### Linux or macOS terminal

Set `project` to the absolute path of your existing application checkout. Keep `package` pointing to the extracted release.

```bash
project="$HOME/projects/example-app"
payload="$package/core/mock2/templates/repo"
upgrader="$payload/.mock2/bin/upgrade.mjs"

node "$upgrader" --from "$payload" --repo "$project" --plan-only
node "$upgrader" --from "$payload" --repo "$project" --commit
```

### PowerShell terminal

```powershell
$project = Join-Path $HOME 'projects/example-app'
$payload = Join-Path $package 'core/mock2/templates/repo'
$upgrader = Join-Path $payload '.mock2/bin/upgrade.mjs'

node $upgrader --from $payload --repo $project --plan-only
node $upgrader --from $payload --repo $project --commit
```

Read the plan before running the apply command. If using a terminal outside the application, run the `git` preparation commands after changing into `$project`, or use `git -C` with that path. The upgrader's `--repo` must name the same checkout and branch you prepared.

The plan writes nothing. Applying checks each incoming template file against its manifest, then updates managed files while preserving the project's adjustments and project-owned files. `--commit` commits the exact eligible paths written by the upgrade when it can complete cleanly. It does not push, rebase, restart a service, install application dependencies, or deploy the application. Review the resulting commit and run the project's established checks before merging or releasing it.

Do not add `--force` to bypass a conflict. The guide's clean-start requirement matters: `--commit` rejects active Git operations and detached HEAD, but is not a blanket check that every tracked file was clean before the run.

### If the upgrader reports conflicts

An edited managed file is kept, and the incoming release version is written beside it as `<file>.mock2-new`. Other safe files may already have been applied. Exit status `1` means unresolved conflicts can remain; it does not mean nothing changed. Review `git status` and the complete upgrader output.

For each conflict, compare the existing file, its `.mock2-new` companion, and the project's own history (`git log -p -- path/to/file`). Combine the new standards with the project adjustment, delete the resolved `.mock2-new` companion, and rerun the same local-folder upgrade. Review and commit any remaining upgrade changes, including `.mock2/installed.json`, as one standards update on this branch. Leave unrelated files out of the commit. The repository is not at a clean release until all reported conflicts are resolved.

Use the normal manual command above for this workflow. `--if-clean` is intended for unattended checks: it can skip the whole apply when a conflict exists and returns zero even when nothing was applied. It is not evidence that a manual upgrade completed.

If interrupted, rerun the same command with the same local payload and repository; the upgrader uses its journal to recover its interrupted writes. Read its result before editing or committing a partial upgrade. If it says a commit was refused, follow the reported recovery state rather than assuming an upgrade commit exists.

## Optional: seed a new repository

The local payload can also add Mock2 files to an empty directory: template paths absent from the target are added, while ownership rules protect existing project files. This creates standards, agents, prompts, and project scaffolding; it does not generate an application or install its dependencies.

Create a new project directory, initialize Git, and make an initial empty commit using your configured Git identity:

```text
git init -b main
git commit --allow-empty -m "chore: initialize project"
git switch -c mock2/standards-1.40.0
```

Then use the same payload and upgrader commands with `--repo` naming that new project. Add `--project-name "Example app"` to both the plan and apply commands to fill the project-name placeholder consistently. Inspect the plan first. A repository with existing files can report conflicts or preserve those files according to ownership; the empty-directory example does not authorize replacing an existing application.

## Where the files go

| Location | Purpose |
| --- | --- |
| Extracted package in your staging folder | Read-only source for a specific release; keep it separate from the project. |
| Target project `.github/agents/` and `.github/prompts/` | Repository-local agents and commands available to supporting editors. |
| Target project `.mock2/` | Managed standards, tools, manifests, and installed-file tracking. |
| Target project `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` | Agent entry points; managed regions are updated while surrounding project text is preserved. |
| Target project `state/` and other project-owned files | Created when absent, preserved when already present according to template ownership. |
| Your home directory `.mock2/`, `.claude/`, and `.copilot/` | Optional user-level installation; separate from the repository-only upgrade. |

Open the target application folder in VS Code after the upgrade. With Remote SSH, use the remote folder containing the application's `.git` and `.github` directories. Reload the editor if its customization list has not refreshed. Other editors can use the same checked-in instructions and terminal tools; editor-specific agent discovery depends on that editor's features. The archive does not install VS Code, an SSH server, Copilot, or other editor extensions.

## Optional: install user-level standards from the transferred package

Repository-local usage above is sufficient when the destination cannot reach the website. If you also want the user-level files, serve the extracted source over loopback on the destination, then point the existing installer at it. This requires Python 3 already installed. Keep the server bound to `127.0.0.1`.

In a separate terminal on that machine, run one of these commands and leave it running:

```bash
python3 -m http.server 8765 --bind 127.0.0.1 --directory "$package"
```

```powershell
python -m http.server 8765 --bind 127.0.0.1 --directory $package
```

In your original terminal, run the installer as the user whose home directory should receive the standards:

```bash
MOCK2_BASE=http://127.0.0.1:8765 bash "$package/install.sh"
```

```powershell
powershell -NoProfile -File (Join-Path $package 'install.ps1') -Base http://127.0.0.1:8765 -Quiet
```

Use `pwsh` in place of `powershell` if that is the installed PowerShell executable. If local execution policy prevents running a script, follow your machine's approved script-execution procedure. Stop the loopback server with Ctrl+C when installation finishes.

The standards files come from the local package. Editor-extension setup may still need marketplace access; extensions are not bundled. The Bash installer can attempt that setup when `code` is present. Use the repository-only route for an upgrade that makes no network requests. Later automatic checks may attempt the configured website and report offline while retaining the installed local standards.

## ZIP updates and a true Git rebase

The ZIP is a snapshot of source files. It does not contain `.git` or the Git objects required to rebase. Applying Mock2 through the local upgrader produces a standards update on your application branch; a Git rebase is not required to consume that package.

If you separately need to rebase an application feature branch while its Git server is unreachable, transfer the application's missing Git history in a Git bundle created from a connected checkout of that same application. The bundle is a separate artifact from the Mock2 ZIP.

Example on a connected checkout, after verifying the branch names and their commits are the ones you intend to transfer:

```text
git bundle create ../application-history.bundle main feature/my-work
git bundle verify ../application-history.bundle
```

Copy `application-history.bundle` to the destination using your normal transfer method. In the existing destination application checkout, inspect `git status`, ensure your work is committed and no Git operation is active, and verify the bundle. Replace the example bundle path with its actual destination path:

```text
git bundle verify /path/to/application-history.bundle
git fetch /path/to/application-history.bundle main:refs/remotes/offline/main
git switch feature/my-work
git merge-base HEAD refs/remotes/offline/main
```

The fetch imports history into an `offline` reference; it does not update the working tree. Confirm the imported commit with `git log` and `git show`. If `merge-base` finds no common ancestor, stop and check that the bundle and checkout are from the same application. The destination feature branch must already exist locally and contain the work you intend to rebase; the example does not replace or reset it from the bundle.

Only when the branch, imported base, and clean working tree are correct, run:

```text
git rebase refs/remotes/offline/main
```

Resolve reported conflicts, stage only the resolved paths, and use `git rebase --continue`; use `git rebase --abort` to return to the pre-rebase branch state if you choose to abandon that rebase. Review and test the result. These commands do not push. Coordinate any later publication of rewritten feature-branch history through your repository's usual process.