# Digital Employee Runbook

This file is the minimal operating contract for calling `docfill` from a digital employee, scheduler, or shell script.

## Inputs

Each run needs:

- A `task.json` config file.
- A data source: `.xlsx` or SQLite `.db`.
- A template: `.docx` or `.xlsx`.
- An output path pattern in `task.json`.

Paths inside `task.json` are resolved from the config file directory.

## Command

```bash
docfill run -c /path/to/task.json --var date=2026-06-18
```

Use repeated `--var key=value` arguments for runtime values:

```bash
docfill run -c task.json --var date=2026-06-18 --var batch=早班
```

CLI variables override `vars` in `task.json`. Row data overrides both.

## Success

Exit code `0`.

Stdout contains generated files:

```text
generated 2 file(s)
- /path/to/out/report_张三.xlsx
- /path/to/out/report_李四.xlsx
```

## Failure

Exit code `1` means the task ran but failed.

Exit code `2` means the command line was invalid.

Errors are written to stderr with the `docfill:` prefix:

```text
docfill: render row 1: missing template field "done"
```

## Common Errors

`missing template field`

The template contains a `{{field}}` that is not present in data, `vars`, or CLI `--var`.

`output already exists`

The output file exists and `output.overwrite` is not `true`.

`missing sqlite params field`

A SQLite query parameter such as `{{date}}` was not provided.

`unresolved placeholder`

The rendered document still contains `{{field}}`. Check the source data value and the template.

## Build

```bash
bash scripts/build.sh
```

The local build output is:

```text
dist/docfill-darwin-arm64
```

## Smoke Test

```bash
bash scripts/smoke.sh
```

Smoke test builds a temporary binary, generates temporary example files, runs both example configs, and checks generated outputs.