---
title: "Getting started with texanshootR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with texanshootR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>",
  eval     = FALSE
)
```

`texanshootR` is a terminal-first specification-search engine. The main
entry point is `shoot()`. It opens a wall-clock budget, fires at the
specification space, and returns a `tx_run` carrying the highlighted
result and the audit trail.

## A first run

```{r}
library(texanshootR)

run <- shoot(mtcars)
print(run)
summary(run)
```

`shoot()` flails opportunistically across predictor subsets,
transformations, interactions, outlier exclusions, subgroup splits, and
— as the career advances — alternative model families. The print method
leads with the shooter's face and the emotional arc the run followed
(`composed -> resolved`, `panicked -> resolved (last-minute)`,
`escalated to derived metrics`) before the formula and the p-value.

Every run is deterministic given a seed. The seed, R version, package
version, and a hash of the search trace are recorded on the returned
object so the full search can be replayed.

## The publication chain

A finished `tx_run` that clears `p <= 0.05` is *shippable*. The first
shippable run opens a **publication chain** — six output stages,
redeemed in order:

```r
abstract(run)            # one-paragraph deadpan summary
manuscript(run)          # IMRaD draft; Methods match the winning spec
presentation(run)        # 8-slide deck; residual plot on slide 7
reviewer_response(run)   # opens "we thank the reviewer..."
graphical_abstract(run)  # the figure your PI will retweet
funding(run)             # the next grant, citing the just-shipped finding
```

Finish the chain through your currently-unlocked prefix and you
collect a length-bonus on top of the per-stage XP.

The chain breaks — bonus forfeit, partial XP kept — if you fire a
fresh `shoot()` before finishing. Calling the wrong stage (or the
wrong run) signals a `tx_chain_error` but leaves the chain open so
you can retry the correct stage.

Aliases are accepted: `powerpoint` (= `presentation`), `reviewer` (=
`reviewer_response`), `graphical` (= `graphical_abstract`).

### XP, chain length, career tier

The chain prefix you can redeem grows with cumulative XP. Career tier
is a label derived from that prefix:

| Chain length | New stage              | XP needed | Career tier        |
|:------------:|------------------------|:---------:|--------------------|
| 1            | `abstract()`           | 0         | Junior Researcher  |
| 2            | `manuscript()`         | 5         | Postdoc            |
| 3            | `presentation()`       | 15        | Postdoc            |
| 4            | `reviewer_response()`  | 30        | Senior Scientist   |
| 5            | `graphical_abstract()` | 55        | Senior Scientist   |
| 6            | `funding()`            | 90        | PI                 |

The tier label is cosmetic. The chain length is the real gate.

## Auto-generating the chain

Output flags on `shoot()` auto-generate the chain prefix needed to
reach the highest enabled flag, in order. So a shippable run with
`presentation = TRUE` produces `abstract`, `manuscript`, and
`presentation` in one go — provided each one is unlocked:

```{r}
run <- shoot(mtcars, presentation = TRUE)
```

Files land in `tempdir()` by default. Override with `output_dir =` or
`options(texanshootR.output_dir = ...)`. Each generator returns the
file path invisibly.

## Locked stages and broken chains

Locked calls, the wrong run, and out-of-order calls all signal a
structured `tx_chain_error`. A locked stage in a fresh profile
looks like this:

```
manuscript() requires:
5 XP (chain length 2)

Current XP:
0
```

Scripts can branch on the `reason` field:

```{r}
res <- tryCatch(manuscript(run), tx_chain_error = function(e) e)
if (inherits(res, "tx_chain_error")) {
  res$reason   # one of: not_unlocked, no_active_chain,
               #         wrong_run, wrong_stage
}
```

Inspect the live HUD with `progress()`:

```{r}
progress()
```

It prints chain length, current XP, next unlock, what's still locked,
and the active chain window if one is open.

## Career, achievements, cosmetics

```{r}
career()        # tier, runs, favourite method, opaque scores
achievements()  # 20 unlockable badges; hidden ones show as ???
wardrobe()      # equipped cosmetic slots (hat, badge, cloak, poncho, lanyard)
run_log()       # tibble of every run on this profile
```

Hidden achievements appear as `???` until unlocked. New cosmetics
auto-equip when their unlocking achievement fires; override the
selection with `wardrobe(slot, id)`.

## Persistent state

The researcher profile persists under
`tools::R_user_dir("texanshootR", "data")` as flat YAML. The first
interactive save prompts before writing anything to disk. Decline the
prompt, or opt out entirely with:

```{r}
options(texanshootR.save_enabled = FALSE)
```

and the package becomes stateless: every call is independent,
progression sits inert at Junior Researcher, and the chain never
opens beyond `abstract()`.

To pre-consent (CI, scripts, the impatient):

```{r}
options(texanshootR.consent = TRUE)
```

## Resetting

Should circumstances call for a fresh start — a new institution, a
co-author dispute, an opportune hard-drive failure, or because some of
you just want to see the world burn:

```{r}
reset_career(force = TRUE)
reset_achievements(force = TRUE)
reset_wardrobe(force = TRUE)
reset_all(force = TRUE)
```

## Next steps

The [README](https://gillescolling.com/texanshootR/) covers the seven
model families, the message-pack schema, and the design philosophy.
The [reference index](https://gillescolling.com/texanshootR/reference/)
lists every exported function with examples.