# Windows repository workflows

## Local uninstall before an npm installation test

Close Accio, Codex, Claude, and active ADH jobs, then double-click
`uninstall-local.cmd` from this directory. No administrator elevation is
requested. The launcher applies PowerShell's execution-policy override only
to its own process. Keep this checkout and its Python 3.12 `.venv` available.

The script removes the current user's ADH product/debug runtime and its
backup payloads, the retired `ADH Dev` directory, `@xuyuanwu/adh` and
`@adhq/adh` from the active/default npm global prefix, this repository's
`dist/npm-publish/smoke` prefix, and every retained Accio bundled Node prefix
at `%APPDATA%\Accio\pre-install\<generation>\node`, ADH user PATH entries, and installed ADH
skills. It removes only the `adh` MCP entry from user/project Codex config
and the current user's Claude Desktop config. Custom configurations in
other projects or manually chosen npm prefixes are not searched globally.

Runtime data at `%LOCALAPPDATA%\ADH` and any configured `ADH_DATA_ROOT`,
repository source, build outputs, release archives, and unrelated packages
are retained. Config backups, the previous user PATH, and the execution log
are saved under `.adh-work/uninstall-<timestamp>`. The operation fails closed
on links, ambiguous config edits, or deletion roots overlapping runtime data.
It can be rerun after an interrupted/partial uninstall.

Read-only preview (no processes stopped or settings changed):

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\windows\uninstall-local.ps1 -Preview
```

After success, sign out/in or restart Windows to clear inherited PATH values.
For Accio testing, reopen the host and run `accio-adh check`, then follow its
`next_action` to install when missing. Accio's bundled npm prefix is separate
from the ordinary terminal's global installation. Accio itself, its plugins,
its Node/npm runtime, unrelated npm packages and account data are preserved.

For a standalone terminal, install with `npm.cmd install -g @xuyuanwu/adh@latest`, run `adh.cmd start` and
`adh.cmd doctor --json`, then register the agent again with
`adh.cmd install agent --client codex --scope user`. This tests a fresh binary
installation against preserved runtime data, not an empty-data first launch.

## Development wrappers

These wrappers operate on the single ADH product runtime at
`%LOCALAPPDATA%\Programs\ADH\payload`. They do not create or register a second
development runtime.

```powershell
scripts\windows\refresh.cmd
scripts\windows\build.cmd
scripts\windows\check.cmd
scripts\windows\smoke.cmd validate
scripts\windows\smoke.cmd run --tier S1 --platform windows
scripts\windows\mcp.cmd
scripts\windows\repl.cmd
scripts\windows\benchmark.cmd
scripts\windows\status.cmd
scripts\windows\stop.cmd
```

`refresh.cmd` builds and statically verifies the canonical release-shaped
payload before stopping the installed runtime. It activates the payload with a
sibling staging/backup swap and restores the previous payload if start or
Doctor readiness fails. The console reports six numbered stages with elapsed
time and prints the last 40 log lines on failure; detailed build output remains
in `.adh-work\logs\refresh.log`. The build wait is bound to the direct build
host so long-lived compiler telemetry descendants cannot stall refresh. After
Doctor succeeds, it normalizes the user `PATH` to
the stable payload, removes obsolete pre-single-runtime entries, and broadcasts
the environment change. Existing shells and agent hosts must restart when the
reported `shell_restart_required` value is true. Use `-Online` when the locked
Python runtime is not yet cached. Use `-SkipBuild` only when
`dist\release\windows\x64` has already passed the release verifier. After
runtime verification, refresh runs
`adh install agent --client codex --scope user` by default so the installed
skill and host MCP configuration stay aligned with the activated payload.
The installation is content-idempotent: an unchanged installed skill is not
replaced, and an already-correct Codex MCP section does not rewrite the user's
top-level `config.toml`. The refresh result reports skill and MCP configuration
updates separately.
Existing `-RegisterAgent` invocations remain
accepted but no longer need the flag. Use `-SkipAgentRegistration` only for a
deliberate payload-only refresh that must leave the installed agent integration
unchanged.

The installed CLI execution surface matches MCP exactly:

```text
start_session / run_python / reset_python / close_session
```