# PR template usage guide

Summarizes the resolution rules, storage locations, and configuration methods for the Markdown template that the host-native `Okstra lead` uses to write the PR body during the `release-handoff` phase.

Authoritative source of the resolution logic: [`scripts/okstra_ctl/pr_template.py`](../scripts/okstra_ctl/pr_template.py).

## 1. The 4-step lookup priority

Higher priority matches first. Once an upper step matches, the lower steps are not consulted.

| # | source | Location | Notes |
|---|--------|------|------|
| 1 | **per-run override** | `okstra render-bundle --pr-template-path <path>` or the wizard's one-time input | A relative path is resolved against the caller cwd (override) or against `project_root` (using the same function as project scope). |
| 2 | **project scope** | the `prTemplatePath` field in `<project_root>/.okstra/project.json` | A relative path is resolved against `project_root`. |
| 3 | **global scope** | the `prTemplatePath` field in `~/.okstra/config.json` | **Only an absolute path or a `~/`-prefixed path** is allowed. A relative path is ambiguous and rejected. |
| 4 | **default (installed runtime)** | the first existing file among the candidate paths (§2 below) | The fallback path right after `npx okstra install`. |

If the file named in any of the 4 steps does not exist, it fails immediately with `PrTemplateError` (no silent fallback).

## 2. Default candidate paths

| # | Path | When it exists |
|---|------|----------------|
| 1 | `$OKSTRA_SKILLS_DIR/okstra-run/templates/pr-body.template.md` | Only when the `OKSTRA_SKILLS_DIR` environment variable is set. Nothing in okstra sets it for you — it is an escape hatch for a non-standard skill home. |
| 2 | `$OKSTRA_HOME/templates/pr/pr-body.template.md` — `~/.okstra/templates/pr/pr-body.template.md` unless `OKSTRA_HOME` overrides the home | The location `npx okstra install` writes to. This is the candidate that normally matches. |

The candidates are tried in priority order, and if all are absent it ends with an explicit error that names every path it searched:

```text
no PR template available: default template not found. Searched: <candidate paths>. Reinstall okstra (`npx okstra install`) or set prTemplatePath in project.json / ~/.okstra/config.json.
```

## 3. The original inside the source repository

- [`templates/pr/pr-body.template.md`](../templates/pr/pr-body.template.md) — the original that `npx okstra install` copies to `~/.okstra/templates/pr/pr-body.template.md` (§2 candidate 2). To change the copy, edit this file and install again.

## 4. Configuration commands — persistence

To keep it longer than a per-run override, either the wizard invokes it automatically or you record it directly with the following commands.

```bash
# project scope: update prTemplatePath in <project_root>/.okstra/project.json
okstra config set pr-template-path "<path>" --scope project

# global scope: update prTemplatePath in ~/.okstra/config.json (absolute path required)
okstra config set pr-template-path "<absolute-path>" --scope global
```

In the wizard flow, the `pr_template_pick` step lets you choose among `Once / Save to project / Save globally`. Choosing `project` or `global` persists `prTemplatePath` with the same effect as the commands above.

## 5. Source tracking

Each run's prepare step records the step actually adopted into ctx, so it can be traced from the final report and elsewhere.

| ctx key | Value |
|---------|-----|
| `PR_TEMPLATE_PATH` | the actually resolved absolute path |
| `PR_TEMPLATE_SOURCE` | one of `"override" \| "project" \| "global" \| "default"` |

If `PR_TEMPLATE_SOURCE` is `default` but the project convention requires a distinct PR body, register `prTemplatePath` with the §4 persistence command.

## 6. Troubleshooting

| Symptom | Cause | Action |
|------|------|------|
| `override PR template not found: <path>` | the path given as a per-run override does not exist | Check for a path typo or use a persisted configuration. |
| `project.json prTemplatePath points to missing file: <path>` | the file pointed at by `prTemplatePath` in `project.json` is absent | Restore that file or reconfigure with `okstra config set pr-template-path <path> --scope project`. |
| `global config prTemplatePath must be absolute or start with '~/'` | a relative path was put in `~/.okstra/config.json` | Update to an absolute path or a `~/`-prefixed path. |
| `no PR template available` | install is missing or even the default file is absent | Re-run `npx okstra install` or set it explicitly with the §4 command. |