> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
> Use this file to discover all available pages before exploring further.

# v0.5.0-rc.2

> 2026-05-02

`v0.5.0-rc.2` adds the `trellis uninstall` command ([#221](https://github.com/mindfold-ai/Trellis/issues/221)) and patches Windows compatibility ([#218](https://github.com/mindfold-ai/Trellis/issues/218)) and Copilot custom-agent frontmatter (PR [#210](https://github.com/mindfold-ai/Trellis/pull/210)). No new migrations.

## Enhancements

### `trellis uninstall` command (#221)

Removes all files generated by trellis along with the `.trellis/` directory. The deletion list is sourced from `.trellis/.template-hashes.json`; files not listed in the manifest are not touched.

```bash theme={null}
trellis uninstall              # default: list + Continue? [Y/n]
trellis uninstall --yes        # skip prompt
trellis uninstall --dry-run    # list then exit, no changes
```

Pre-checks:

| Condition                                              | Behavior                                                          |
| ------------------------------------------------------ | ----------------------------------------------------------------- |
| `.trellis/` directory missing                          | Friendly exit 0 with `"Trellis is not installed in this project"` |
| `.trellis/` exists but `.template-hashes.json` missing | Exit 1 with hint to delete `.trellis/` manually                   |
| Both present                                           | Proceed to scan + listing                                         |

Output is split into two columns:

* **Will be deleted** — opaque files (`.py` / `.md` / `.ts`) plus structured-config files that scrub down to nothing, plus the `.trellis/` directory itself.
* **Will be modified** — structured-config files where trellis-owned entries are stripped but user-added fields are preserved.

Four scrubbers cover 11 structured config files:

| Scrubber                   | Files                                                                                                                                               |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scrubHooksJson` (nested)  | `.claude/settings.json`, `.gemini/settings.json`, `.factory/settings.json`, `.codebuddy/settings.json`, `.qoder/settings.json`, `.codex/hooks.json` |
| `scrubHooksJson` (flat)    | `.cursor/hooks.json`, `.github/copilot/hooks.json`                                                                                                  |
| `scrubOpencodePackageJson` | `.opencode/package.json` — removes `dependencies["@opencode-ai/plugin"]`                                                                            |
| `scrubPiSettings`          | `.pi/settings.json` — strips trellis entries from `extensions` / `skills` / `prompts` arrays; removes `enableSkillCommands`                         |
| `scrubCodexConfigToml`     | `.codex/config.toml` — removes `project_doc_fallback_filenames` and the trellis NOTE comment block                                                  |

Command matching rule: only the last whitespace token of a `command` string (the script path) is used for comparison. Substring occurrences elsewhere (e.g. inside an `echo`) do not match.

Execution order: scrubber → `unlink` → `cleanupEmptyDirs` (prunes emptied subdirectories) → managed-root sweep (prunes empty `.claude/` / `.cursor/` / etc. top-level dirs) → `rm -rf .trellis/`. Directories that still contain user files are preserved.

Manifest-listed paths are removed unconditionally; no hash check is performed. User-modified trellis files are deleted as well.

23 new tests (15 scrubber unit + 8 integration); 830 tests pass overall.

## Bug Fixes

### Windows `python3` → `python` at write time (#218, PR [#220](https://github.com/mindfold-ai/Trellis/pull/220))

Windows has no `python3` executable. `replacePythonCommandLiterals()` runs at init/update write time on `process.platform === "win32"`:

```ts theme={null}
content
  .split('\n')
  .map((line) => (line.startsWith('#!') ? line : line.replaceAll('python3', 'python')))
  .join('\n');
```

* **Write-time only** — template source files keep `python3`; replacement happens at file generation time.
* **Shebang preserved** — lines beginning with `#!` are not replaced.
* **Idempotent** — `python` does not contain `python3`; running multiple times produces the same result.
* **Coverage** — `configurators/{claude,codex,copilot,opencode,pi}.ts`, `configurators/shared.ts` (`writeSkills` / `writeAgents` / `writeSharedHooks` / `resolvePlaceholders` / `buildPullBasedPrelude`), `configurators/workflow.ts`, `templates/extract.ts`, `configurators/index.ts` (`collectPlatformTemplates`), `commands/update.ts` (`collectTemplateFiles`). init and update produce byte-for-byte identical output on Windows.

9 new platform-mocked unit tests in `test/configurators/shared.test.ts` cover win32/linux/darwin behavior, shebang preservation, multiline content, idempotency, and the documented `python3x` substring boundary.

### Copilot custom agent tools frontmatter (PR [#210](https://github.com/mindfold-ai/Trellis/pull/210))

`injectPullBasedPreludeMarkdown()` now uses a regex frontmatter splitter (`splitMarkdownFrontmatter`) instead of line-based scanning, handling CRLF endings cleanly. `mapLegacyToolToCopilot()` translates Claude-style tool tokens (`Read`, `Write`, `Edit`, `Glob`, ...) into Copilot's lowercase shape (`read`, `edit`, ...) so custom agents authored against the Claude convention render correctly under Copilot. Regression coverage added in `test/regression.test.ts`.

## Upgrade

```bash theme={null}
npm install -g @mindfoldhq/trellis@rc
trellis update
```

Projects on 0.5 (beta or earlier rc) run `trellis update`. Projects upgrading from 0.4.x run `trellis update --migrate` because the 0.5 migration chain begins at 0.5.0-beta.0. rc.2 adds no new migration entries.