chore: prepare docfill project for gitea

docs/digital-employee-runbook.md

@@ -8,11 +8,14 @@ Each run needs:
 
 - A `task.json` config file.
 - A data source: `.xlsx` or SQLite `.db`.
+- Optional business filters in `filter.equals`.
 - A template: `.docx` or `.xlsx`.
 - An output path pattern in `task.json`.
 
 Paths inside `task.json` are resolved from the config file directory.
 
+Use one `task.json` per business task. Use `--var` for values that change per run, such as date, ticket number, person, or batch.
+
 ## Command
 
 ```bash
@@ -22,10 +25,42 @@ 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=早班
+docfill run -c task.json --var date=2026-06-18 --var ticket_no=GD-002
 ```
 
-CLI variables override `vars` in `task.json`. Row data overrides both.
+Priority:
+
+```text
+row data > CLI --var > task.json vars
+```
+
+CLI variables override `vars` in `task.json`. The selected row data overrides both when rendering templates and output paths.
+
+If `task.json` has a filter:
+
+```json
+"filter": {
+  "equals": {
+    "日期": "{{date}}",
+    "工单编号": "{{ticket_no}}"
+  },
+  "expect": "one"
+}
+```
+
+then the command:
+
+```bash
+docfill run -c task.json --var date=2026-06-18 --var ticket_no=GD-002
+```
+
+selects the row where `日期 = 2026-06-18` and `工单编号 = GD-002`.
+
+Use `--verbose` only when diagnosing a failed or suspicious run:
+
+```bash
+docfill run -c task.json --var date=2026-06-18 --var ticket_no=GD-002 --verbose
+```
 
 ## Success
 
@@ -48,9 +83,91 @@ 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"
+docfill: [TEMPLATE_FIELD_MISSING] render row 1: missing template field "done"
+hint: Add column "done" to the data source or pass --var done=...
+context: field=done template=/path/template.docx
 ```
 
+Verbose logs are also written to stderr:
+
+```text
+log: load config path=/path/task.json
+log: read data type=excel path=/path/data.xlsx
+log: read data type=excel path=/path/data.xlsx rows=3
+log: filter rows=3 matched=1 expect=one
+log: render row=1 output=/path/out/work_order_2026-06-18_GD-002.docx
+```
+
+## Error Codes
+
+`CLI_USAGE`
+
+The command line is invalid.
+
+`CONFIG_READ`
+
+The config file cannot be read.
+
+`CONFIG_PARSE`
+
+The config file is not valid JSON.
+
+`CONFIG_VALIDATE`
+
+The config is missing required fields or uses unsupported values.
+
+`DATA_EXCEL`
+
+Excel data cannot be opened or read.
+
+`DATA_SQLITE`
+
+SQLite data cannot be opened, queried, or parameterized.
+
+`DATA_EMPTY`
+
+The data source returned no rows.
+
+`DATA_FILTER_FIELD`
+
+The filter references a field that is not in the data.
+
+`DATA_FILTER_VALUE`
+
+The filter references a variable that was not provided.
+
+`DATA_FILTER_NO_MATCH`
+
+The filter matched no rows.
+
+`DATA_FILTER_MULTI_MATCH`
+
+The filter expected one row but matched multiple rows.
+
+`TEMPLATE_OPEN`
+
+The template file cannot be opened or inspected.
+
+`TEMPLATE_FIELD_MISSING`
+
+The template references a field that is not available.
+
+`TEMPLATE_UNRESOLVED`
+
+The rendered file would still contain a `{{field}}` placeholder.
+
+`OUTPUT_EXISTS`
+
+The output file exists and overwrite is not enabled.
+
+`OUTPUT_WRITE`
+
+The output directory or file cannot be written.
+
+`INTERNAL`
+
+An unexpected unclassified error occurred.
+
 ## Common Errors
 
 `missing template field`
@@ -65,6 +182,18 @@ The output file exists and `output.overwrite` is not `true`.
 
 A SQLite query parameter such as `{{date}}` was not provided.
 
+`filter matched no rows`
+
+Check `filter.equals`, `--var` values, or the source table contents.
+
+`filter matched N rows but expected one`
+
+Add another filter condition or clean duplicate rows in the source table.
+
+`filter field is not in data`
+
+Check Excel headers or SQLite query column names.
+
 `unresolved placeholder`
 
 The rendered document still contains `{{field}}`. Check the source data value and the template.
@@ -87,4 +216,4 @@ dist/docfill-darwin-arm64
 bash scripts/smoke.sh
 ```
 
-Smoke test builds a temporary binary, generates temporary example files, runs both example configs, and checks generated outputs.
+Smoke test builds a temporary binary, generates temporary example files, runs example configs including the filter case, and checks generated outputs.