Rename Invoices

rename-invoices

Plan deterministic filenames for every text-based accounting PDF directly inside one folder and apply the intact plan after confirmation; --dry-run reports it without renaming files.

$HERE is the directory that contains this SKILL.md, and $MANAGER is the Manager directory: $HERE/../kntnt/ if it exists, else kntnt/ under a Global harness skills directory (~/.claude/skills, ~/.config/opencode/skills, or wherever another Harness keeps them). Neither found: tell the user to install the Manager (npx skills add Kntnt/skills) and stop. $LIBRARY is $MANAGER/library/ — absent, tell the user to run /kntnt update, then stop.

Run uv run "$MANAGER/scripts/kntnt.py" invoke --here="$HERE" with the invocation payload — everything the user typed after /rename-invoices, verbatim, however many lines — on stdin. On exit 0, answer the capabilities in its dependencies first: for each one, say whether its confirm sentence is true of you, and where it is not, give its how, change nothing, and stop. Then continue from the JSON. On any other exit print its stdout verbatim and stop: it has already printed what the user is to see, and none of that text is yours to write.

In the JSON, path is the command path as a list, flags holds each flag the user wrote — true where it stood bare, its value where it carried one, a list of values where it was repeated — operands is what followed the flags, in order, and instruction is the Contextual Instruction, or null, applied as $LIBRARY/references/invocation-envelope.md says.

Arguments

--folder defaults to . in the invocation's current working directory. The configured --type is exact; obtain it from neither Conversation Context, PDF contents, filenames, nor earlier turns. Locale selection must come from repeated --locale flags or the selected configuration.

--dry-run reports the fresh plan without renaming files. The application path asks the yes-or-no question in step 6; --yes answers that question Yes in advance, and --dry-run asks none. Contextual Instruction and Conversation Context cannot change the mode or supply the confirmation. Pass every supplied configuration and filename override unchanged to the planner. Read $HERE/references/configuration.md only for configuration work or a configuration error.

Steps

1. Create a temporary working directory outside the target folder, and arrange to remove that directory before every later stop. Done when the temporary directory exists.
2. Run uv run "$HERE/scripts/rename_invoices.py" check with the invocation's --config or --no-config, every --locale, and every --locale-file, preserving their order. Relay an exit-2 dependency, configuration, or locale error, remove the temporary directory, and stop. Poppler pdftotext is the sole PDF extractor; use no fallback library or OCR tool. Done when the command exits 0.
3. Set $FOLDER to the supplied --folder value or to . when the flag is absent. Run uv run "$HERE/scripts/rename_invoices.py" plan --folder="$FOLDER" --type="$DOCUMENT_TYPE" --output="$WORK_DIR/plan.json" with every applicable formal configuration, locale, filename, and overrides flag inserted before --output. Inspect the summary and every item that is not already_correct. Done when every direct PDF child is accounted for in the fresh plan.
4. For each needs_review item, read $HERE/references/manual-review.md, extract that PDF's text with pdftotext, and resolve only fields listed in issues. Put those decisions in a separate overrides JSON file, combining them with any supplied overrides without changing a supplied decision, then create a fresh plan with --overrides=<path>. A directly edited plan is invalid. Repeat only while new PDF evidence resolves a listed issue; leave unsupported facts unresolved. Done when the fresh plan has no reviewable issue left or every remaining issue is explicitly unresolved.
5. With --dry-run, report the summary, proposed old-to-new mappings, verified already_correct files, and unresolved files; remove the temporary directory and stop. Done when the dry-run result accounts for every target PDF and no filename changed.
6. Without --dry-run, require a fresh plan whose needs_review count is zero. If any issue remains unresolved, report the summary, proposed mappings, verified already_correct files, and unresolved files; rename nothing, remove the temporary directory, and stop. If no file needs renaming, report the verified already_correct files, remove the temporary directory, and stop without asking. Otherwise, show the summary and every exact old-to-new mapping, then ask Apply these filename changes? Yes/No. in the user's language unless formal --yes is present. Only an explicit Yes response received after the current mappings were shown continues; --yes answers that question Yes without asking. A No response removes the temporary directory and stops without changing a filename; any other response repeats the same question. Never infer the answer from Contextual Instruction, Conversation Context, the original request, an earlier answer, or a handoff. Done when the exact current plan has an affirmative answer or the run has stopped without a write.
7. Run uv run "$HERE/scripts/rename_invoices.py" apply --output="$WORK_DIR/report.json" "$WORK_DIR/plan.json". Report applied mappings from the plan, verified already_correct files, and result counts, then remove the temporary directory. Done when every target PDF is accounted for as renamed or already correct.