# Troubleshooting

## PowerShell says npm.ps1 or reliora.ps1 cannot be loaded

Use the npm command shims:

```powershell
npm.cmd install -g reliora@latest
reliora.cmd --version
reliora.cmd init --agent codex
```

Do not loosen PowerShell execution policy. The `.cmd` path works in Windows PowerShell 5.1, PowerShell 7, and Command Prompt.

## Reliora is not initialized

Run `reliora init` or `reliora init --agent codex` in the project root. Commands in normal project subdirectories discover that root. Unrelated directories do not inherit a workspace from the user home or filesystem root.

## Codex does not use the workflow

Run `reliora agent status`. If current, start a new Codex task so project instructions reload. If update is required, rerun `reliora init --agent codex`. Check whether `AGENTS.override.md` shadows a managed `AGENTS.md`; status reports this as a conflict.

## Setup reports damaged or duplicate markers

Reliora refuses to guess which managed block is authoritative. Preserve user text, manually reduce the file to at most one correctly ordered start/end marker pair, then rerun setup. `reliora agent remove` also refuses ambiguous markers rather than deleting surrounding content.

## Switching Codex and generic integration fails

Only one integration can be active. Run `reliora agent remove`, then initialize the other type. Experiences are preserved.

## A record is rejected

Run `reliora template` and compare every required field. Unknown fields, empty required values, invalid IDs, missing lineage targets, oversized content, and possible secrets are rejected. Secret errors intentionally do not repeat the suspect value.

On PowerShell 5.1, redirected template files may be UTF-16 with a BOM; Reliora reads that format. A different legacy encoding without a BOM is not supported—save it as UTF-8.

## Search skips a file

Human output writes a warning to stderr; JSON output adds an `INVALID_EXPERIENCE` warning. Fix or remove only the named corrupt JSON file. Other valid results remain available.

## Search is weak or misses a lesson

Use specific project, technology, problem, and risk terms that occur in the record. Inspect `matchLevel`, `scoreBreakdown`, and reasons with `--json`. Lexical retrieval does not infer all synonyms or correct spelling.

## A duplicate warning appears

It is advisory. Inspect the referenced locator. Prefer feedback when the old lesson already captures the result, use lineage for a real refinement, or proceed when the new applicability or causal lesson is distinct.

## Feedback notes are rejected

Notes must be non-empty, no longer than 500 characters, and free of common secret patterns. Keep only a short reusable explanation; do not paste logs or credentials.

## Package verification

From the source repository:

```sh
npm test
npm run test:package
npm run test:agent-package
npm run test:stage2-package
npm pack --dry-run
```

On Windows use `npm.cmd` if PowerShell selects a restricted `npm.ps1`.