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

# Compatibility

> Support matrix, upgrade rules, and versioning contract for unch.

## Module path compatibility

* Canonical module path: `github.com/uchebnick/unch`
* Canonical source install path: `github.com/uchebnick/unch/cmd/unch@latest`
* Older `unch-searcher` references should be treated as legacy

## CLI compatibility

* Existing commands and flags are expected to stay stable across patch releases
* Breaking CLI changes should only happen in minor releases
* New flags should be additive

## Manifest compatibility

* Local repository state lives in `.semsearch/manifest.json`
* Manifest compatibility is governed by `schema_version`
* `version` is the logical publication or generation number of indexed repo state
* Remote binding metadata also lives in the manifest, which means remote configuration is checkout-local state

## Index compatibility

* `index.db` is a rebuildable cache artifact, not a durable user database
* Active index state is provider-scoped and model-scoped
* When the current binary cannot use a database layout, the fix is to rebuild the index

## Remote and CI compatibility

* Remote sync trusts published state only when it is compatible with the local binary
* If a published remote index uses an older incompatible schema, local search should keep using a compatible local cache when available
* Repositories that use remote indexing must rerun `.github/workflows/unch-index.yml` after incompatible indexing releases
* A local reindex detaches remote binding and returns the manifest to local-only mode until the checkout is rebound

## Support matrix

| Area                     | Status    | Notes                                                                                                                                                                        |
| ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Go indexing              | Supported | Tree-sitter-based symbol extraction                                                                                                                                          |
| Rust indexing            | Supported | Tree-sitter-based symbol extraction                                                                                                                                          |
| TypeScript indexing      | Supported | Tree-sitter-based symbol extraction                                                                                                                                          |
| JavaScript indexing      | Supported | Tree-sitter-based symbol extraction                                                                                                                                          |
| Python indexing          | Supported | Tree-sitter-based symbol extraction                                                                                                                                          |
| Other languages          | Limited   | Legacy prefix fallback only                                                                                                                                                  |
| Search modes             | Supported | `auto`, `semantic`, `lexical`                                                                                                                                                |
| Homebrew install         | Supported | macOS-first polished install path                                                                                                                                            |
| `go install`             | Supported | CLI package path is `github.com/uchebnick/unch/cmd/unch`; requires a cgo-capable Go toolchain                                                                                |
| `install.sh`             | Supported | Uses release assets on macOS and Linux by default, verifies downloads against published checksums, and falls back to `go install` only when no matching archive is available |
| `install/install.ps1`    | Supported | Uses release assets on Windows by default, verifies downloads against published checksums, and falls back to `go install` only when no matching archive is available         |
| Darwin release binaries  | Supported | `arm64` and `x86_64`                                                                                                                                                         |
| Linux release binaries   | Supported | `arm64` and `x86_64`                                                                                                                                                         |
| Windows release binaries | Supported | `arm64` and `x86_64`                                                                                                                                                         |
| Remote indexing          | Supported | GitHub Actions remote index workflow (`unch-index.yml`)                                                                                                                      |

Published release binaries and CI builds on macOS, Linux, and Windows arm64/x86\_64 use the full cgo-backed Tree-sitter and SQLite stack. Manual Windows builds without cgo remain a fallback path and should not be treated as identical to the published binaries. `go install` is smoke-tested in CI in the official Debian-based Go container image; `install.sh` is smoke-tested on Ubuntu, Debian, Arch, and NixOS-like Linux environments; `install/install.ps1` is smoke-tested on Windows `arm64` and `x86_64`.

<AccordionGroup>
  <Accordion title="CLI stability">
    Existing commands and flags are expected to stay stable across patch releases.

    Breaking CLI changes should only happen in minor releases, and new flags should be additive.
  </Accordion>

  <Accordion title="Manifest and index state">
    Local repository state lives in `.semsearch/manifest.json`.

    `schema_version` governs manifest compatibility, while `index.db` remains a rebuildable cache artifact rather than a durable user database.
  </Accordion>

  <Accordion title="Remote and CI state">
    Remote sync only trusts published state when it is compatible with the local binary.

    If a published remote index uses an older incompatible schema, local search should keep using a compatible local cache when available.
  </Accordion>

  <Accordion title="Practical upgrade rule">
    If `unch` upgrades and local search breaks, rerun `unch index`.

    If remote sync reports an incompatible published schema, rerun `.github/workflows/unch-index.yml`.
  </Accordion>
</AccordionGroup>

## Practical upgrade rules

* If `unch` upgrades and local search breaks, rerun `unch index`
* If remote sync reports an incompatible published schema, rerun the repository remote index workflow
* If you automate installation from source, use `go install github.com/uchebnick/unch/cmd/unch@latest`