# Installation and upgrades

## Requirements

- Node.js 24
- DeepSeek Harness `0.1.1-rc.2` or later
- A writable DSH Workspace

Install J4Agent into every Profile that should expose its UI or Agent tools. Keep the version pinned.

## Install from a Git tag

```bash
dsh plugin --profile web add github:esonx/dsh-project-j4agent#v0.2.0-alpha.1
dsh --profile web --dump-config
dsh web
```

## Install from a Release tarball

Download both `dsh-project-j4agent-0.2.0-alpha.1.tgz` and `SHA256SUMS`, verify the digest, then run:

```bash
dsh plugin --profile web add ./dsh-project-j4agent-0.2.0-alpha.1.tgz
dsh --profile web --dump-config
dsh web
```

Use a new test Profile first when changing DSH or J4Agent versions. Confirm that the plugin tree resolves, the Project Center dialog opens, and a Workspace can be initialized with a Work Item before upgrading a working Profile.

## Upgrade

1. Stop DSH processes using the target Profile.
2. Back up each relevant Workspace's `j4agent/` directory, including any `j4agent.sqlite-wal` and `j4agent.sqlite-shm` files.
3. Install the new pinned tag or tarball with the plugin manager.
4. For `v0.1.x → v0.2.0-alpha.1`, do not open the old database for writes. `v0.2.0-alpha.1` uses a fresh Agent-native schema and intentionally returns `J4_SCHEMA_RESET_REQUIRED` for old stores; it does not migrate or delete them.
5. Keep the backup, then initialize `v0.2.0-alpha.1` in a new Workspace or explicitly move the old `<workspace>/j4agent/` directory aside before initializing a fresh Project.
6. Run `--dump-config`, start DSH and verify the newly initialized Project before development writes.

Do not replace or copy a live SQLite database while DSH is running.

## Uninstall

```bash
dsh plugin --profile web remove dsh-project-j4agent
```

Uninstalling the plugin does not delete `<workspace>/j4agent/`. Remove that data manually only after DSH is stopped and a backup is no longer needed.