# ITHZ-MCP Installation Guide

This guide shows how to add ITHZ-MCP to a project as deterministic agent work memory.

Product model:

```text
project.md
project.ithz
```

`project.md` is the bootstrap file for humans and agents. `project.ithz` is the memory zone for workflow profiles, prompt summaries, decisions, gates, risks, context commits, indexes and snapshots.

ITHZ-MCP does not replace Git, a production database, cloud sync or every retrieval system.

## Prerequisites

- Windows PowerShell.
- Python 3.12 or another Python 3 version that can run the package.
- The product candidate package, for example:

```powershell
C:\work\ITHKOR\ithz_mcp\dist\ithz_mcp-v0.1-product-candidate
```

- `ithz-native.exe` must be available. The product candidate package includes bundled native binaries under `native\`.

Native selection order:

1. `--native-exe <path>` if provided.
2. `ITHZ_NATIVE_EXE` environment variable if set.
3. Bundled `native\ithz-native.exe`, `native\ithz-native-avx2.exe` or `native\ithz-native-scalar.exe`.
4. Sibling development builds under `C:\work\ITHKOR\native_ithz\build_*`.

AVX2 is selected only when runtime CPU support is detected. Scalar is the fallback.

Windows signing note:

- current test builds can be self-signed with `tools/sign_windows_release.ps1`;
- self-signed signatures identify the local test build but do not provide public SmartScreen or antivirus reputation;
- a public trusted Windows release should use OV/EV Authenticode signing plus SHA-256 checksums and AV false-positive submission.

## Option A: Use The Product Candidate Package

Open PowerShell:

```powershell
cd C:\work\ITHKOR\ithz_mcp\dist\ithz_mcp-v0.1-product-candidate
.\smoke_test.ps1
```

If smoke passes, use `python -m ithz_mcp` from this folder or add the folder to your normal tool path.

Quick check:

```powershell
python -m ithz_mcp version
python -m ithz_mcp run-mcp21-production-readiness
```

## Option B: Use The Development Checkout

```powershell
cd C:\work\ITHKOR\ithz_mcp
python -m ithz_mcp version
python -m ithz_mcp run-ci-fast
```

Use this when developing ITHZ-MCP itself. Use the package folder for normal project installation tests.

## Install Into A New Project

Example target project:

```powershell
$Project = "C:\work\my_project"
```

The simplest path is to run the installer from the directory that should own the memory zone:

```powershell
cd $Project
python -m ithz_mcp install-project --apply
```

`install-project` uses the current directory as the project root. It does not climb to the Git root, which is important for monorepos or folders that contain multiple independent projects. If the directory is inside Git, it installs the local ITHZ diff/merge driver for `project.ithz`, but it does not commit anything.

For teammate onboarding, copy `install_ithz.md` into the target project and ask the local agent to follow it. The file is a self-contained bootstrap playbook: it tells the agent to locate a trusted ITHZ-MCP package, run smoke checks, install into the current directory, preserve any existing `project.ithz`, import only redacted prompt-history summaries and report the result. If no trusted package URL or local package path is available, the agent must ask instead of guessing a random GitHub source. `ithz_mcp.md` remains available as the longer reference.

On macOS without a compatible `ithz-native` binary, the agent must not ask a generic "how should I proceed" question. The safe default is to install what works officially now: Cursor/Codex/Claude/Antigravity MCP host config, `*.ithz` Git diff/merge driver, ITHZ Drive/open-temp fallback if present, and a native-binary gap report. Native `project.ithz` creation or rewrite is deferred until `ITHZ_NATIVE_EXE` points to a compatible macOS binary.

If `project.ithz` already exists, `install-project --apply` verifies and reuses it. It does not rebuild the archive from scratch. Workflow profile adoption and optional agent-history import append sanitized memory into the existing archive.

If `.gitignore` already exists, the installer preserves it and appends only missing local ITHZ/host artifacts such as `.ithz-install/`, `.ithz-context/`, `.antigravity/`, `.claude/`, `.cursor/`, `project.ithz.lock` and native diagnostic plan outputs. If `.gitignore` is missing, it creates a minimal one. The operation is idempotent.

If `.gitattributes` already exists, the installer preserves it and appends only the ITHZ archive driver line:

```text
*.ithz merge=ithz diff=ithz binary
```

Optional full host registration for Codex:

```powershell
python -m ithz_mcp install-project --apply --install-codex-config
```

Installer scratch files are written under `.ithz-install\tmp\` and cleaned after a successful install. After a normal install, `.ithz-install\` should contain only `install.log`. Persistent installer files are kept only when explicitly requested:

```powershell
python -m ithz_mcp install-project --apply --keep-install-artifacts
```

Native archive builds use `compact-v2` by default. This keeps deterministic file summaries plus decision/gate/risk/symbol evidence, while avoiding the older duplication of every ordinary text line into `index.json` and `context_units.jsonl`.

Create an onboarding prompt file if you already have workflow rules:

```powershell
@"
Project workflow:
- read project.md first
- ask ITHZ-MCP for a context pack before broad codebase reads
- run tests before final answer
- write an end-of-task checkpoint
"@ | Set-Content -Encoding UTF8 C:\work\tmp\my_project_onboarding.md
```

Adopt the project:

```powershell
python -m ithz_mcp archive-adopt-project-workflow `
  --project $Project `
  --profile gobi `
  --owner "Gobi" `
  --prompt C:\work\tmp\my_project_onboarding.md
```

This creates or validates:

```text
project.md
project.ithz
```

Check it:

```powershell
python -m ithz_mcp archive-memory-status --project $Project
python -m ithz_mcp archive-search-context --project $Project --query "workflow gates risks" --limit 10
New-Item -ItemType Directory -Force -Path "$Project\.ithz-install\tmp" | Out-Null
python -m ithz_mcp archive-get-context-pack --project $Project --query "current workflow and safety rules" --max-bytes 12000 --out "$Project\.ithz-install\tmp\my_project_context_pack.md"
```

## Install Into An Existing Markdown-Heavy Project

If the project already has `README.md`, `ARCHITECTURE.md`, decision logs, workflow docs or old status docs, adopt it with Markdown mining enabled:

```powershell
python -m ithz_mcp archive-adopt-project-workflow `
  --project $Project `
  --profile gobi `
  --owner "Gobi" `
  --prompt C:\work\tmp\my_project_onboarding.md
```

Existing Markdown files are mined into `project.ithz`. They are not deleted or moved.

To audit what could later become memory instead of long-term Markdown:

```powershell
python -m ithz_mcp audit-markdown-memory --project $Project
New-Item -ItemType Directory -Force -Path "$Project\.ithz-install\tmp" | Out-Null
python -m ithz_mcp plan-markdown-migration --project $Project --out "$Project\.ithz-install\tmp\markdown_migration_plan.md"
```

Migration planning is dry-run by default. Do not delete project docs automatically.

## Remove ITHZ-MCP From A Project

Preview first:

```powershell
cd $Project
python -m ithz_mcp uninstall-project
```

Apply removal:

```powershell
python -m ithz_mcp uninstall-project --apply
```

This removes `project.ithz`, `project.md`, `.ithz-install`, the ITHZ `.gitattributes` line, the ITHZ `.gitignore` block, local Git driver config and project-local MCP host configs that contain ITHZ markers. This includes `.mcp.json`, `.antigravity/mcp.json`, `.cursor/mcp.json` and `.claude/mcp.json` when they are ITHZ-generated. It does not run `git add`, `git commit`, `git reset` or `git checkout`.

If you want to keep the bootstrap file:

```powershell
python -m ithz_mcp uninstall-project --apply --keep-project-md
```

Keep project-local host configs explicitly:

```powershell
python -m ithz_mcp uninstall-project --apply --keep-host-configs
```

## Import Historical Agent Prompts

Discovery is dry-run by default:

```powershell
python -m ithz_mcp agent-history-discover `
  --project $Project `
  --source codex `
  --source antigravity `
  --author "Gobi" `
  --max-records 50
```

Write summaries into `project.ithz` only when you explicitly choose to import:

```powershell
python -m ithz_mcp archive-import-agent-history `
  --project $Project `
  --source codex `
  --source antigravity `
  --author "Gobi" `
  --apply
```

Prompt memory defaults to summaries and redaction. Raw full local prompt storage is explicit and is not pushed by team sync.

## Generate MCP Host Installers

Generate host configs for the actual target project. Do not reuse a sample-project config for a different project.

```powershell
$InstallerOut = Join-Path $Project ".ithz-install\host_installers"
python -m ithz_mcp write-host-installers --project $Project --out $InstallerOut
```

`write-host-installers` is the explicit command for persistent host installer files. The one-command `install-project` path cleans its own temporary installer files by default.

Validate one config:

```powershell
python -m ithz_mcp mcp-config-validate --config "$InstallerOut\codex_mcp_config.sample.json"
python -m ithz_mcp mcp-client-smoke --config "$InstallerOut\codex_mcp_config.sample.json" --out "$InstallerOut\codex_smoke_transcript.jsonl"
```

The scripted smoke validates the local MCP protocol surface. A real host UI smoke should still be done inside each host.

Generated Codex configuration contains two profiles:

- `ithz_mcp`: read-only memory-first startup, search and context-pack tools.
- `ithz_mcp_write`: explicit write-enabled end-of-task memory writes.

The write-enabled profile exposes `ithz_archive_auto_checkpoint`. Compatible hosts receive server instructions to call it at the end of a completed task before the final answer, unless the user opts out or the task produced no durable project memory. This is automatic in workflow, but still explicit as a visible MCP tool call into `project.ithz`.

## Codex Install

Dry-run first:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$InstallerOut\install_codex_mcp.ps1"
```

Apply after review:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$InstallerOut\install_codex_mcp.ps1" -Apply
```

This appends the generated `ithz_mcp` read-only server entry and `ithz_mcp_write` write-enabled server entry to `~\.codex\config.toml` and creates a `.bak` backup first.

Start a new Codex thread in the project. The intended startup is:

1. Read `project.md`.
2. Call `ithz_context_status`.
3. Call `ithz_workflow_profile_status`.
4. Call `ithz_archive_get_context_pack` for the task.
5. Inspect only the candidate files and evidence gaps from the pack.
6. At the end of completed work, call `ithz_archive_auto_checkpoint` through the write-enabled profile before the final answer.

## Claude Code Install

Dry-run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$InstallerOut\install_claude_code_mcp.ps1" -Project $Project
```

Apply:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$InstallerOut\install_claude_code_mcp.ps1" -Project $Project -Apply
```

This writes a project `.mcp.json` style config. Host-specific config formats can change, so validate with the host's own MCP tooling after install.

## Cursor Install

Dry-run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$InstallerOut\install_cursor_mcp.ps1" -Project $Project
```

Apply:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$InstallerOut\install_cursor_mcp.ps1" -Project $Project -Apply
```

This writes:

```text
<project>\.cursor\mcp.json
```

## Antigravity Install

Dry-run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$InstallerOut\install_antigravity_mcp.ps1" -Project $Project
```

Apply:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$InstallerOut\install_antigravity_mcp.ps1" -Project $Project -Apply
```

This writes:

```text
<project>\.antigravity\mcp.json
```

If your installed Antigravity build expects another config location, copy the generated JSON into that location and keep the `command`, `args`, `mode=read-only` and `storage_profile=native-archive` values.

## Team Git Setup

Track the two project files:

```powershell
git add project.md project.ithz
git commit -m "Add ITHZ-MCP project memory zone"
```

Install the ITHZ-aware Git diff/merge driver:

```powershell
python -m ithz_mcp install-git-drivers --repo $Project --dry-run
python -m ithz_mcp install-git-drivers --repo $Project
```

This configures:

```text
*.ithz merge=ithz diff=ithz binary
```

Git remains the transport. ITHZ-MCP performs semantic diff/merge for `project.ithz`.

## Normal End-Of-Task Write

Read-only MCP is the normal startup mode. Write memory explicitly at the end:

```powershell
python -m ithz_mcp archive-finalize-task `
  --project $Project `
  --task "Implemented feature X" `
  --summary-text "Feature X was implemented and tested." `
  --decision "Use approach A because it keeps the existing API stable." `
  --gate "run-ci-fast passed" `
  --risk "Watch migration edge cases" `
  --next "Run broader smoke on staging" `
  --docs-impact updated `
  --memory-impact handoff-created `
  --include-git
```

Then commit:

```powershell
git add project.md project.ithz
git commit -m "Update project memory after feature X"
```

## Validation Checklist

Run after installation:

```powershell
python -m ithz_mcp archive-memory-status --project $Project
New-Item -ItemType Directory -Force -Path "$Project\.ithz-install\tmp" | Out-Null
python -m ithz_mcp archive-get-context-pack --project $Project --query "current status gates risks next steps" --max-bytes 12000 --out "$Project\.ithz-install\tmp\ithz_pack.md"
python -m ithz_mcp mcp-config-validate --config "$InstallerOut\codex_mcp_config.sample.json"
python -m ithz_mcp mcp-client-smoke --config "$InstallerOut\codex_mcp_config.sample.json" --out "$InstallerOut\smoke_transcript.jsonl"
```

Expected result:

- `project.md` exists.
- `project.ithz` exists.
- `archive-memory-status` reports safe verification.
- MCP config validates.
- Scripted MCP smoke passes.
- Secret-like files are not included.
