# Eight workshop notes: complete file-naming kit

Start with the [English tutorial](/blog/content-based-file-naming-packet/) and [full readable preview](/blog/assets/content-based-file-naming-packet/en/readable-preview.md). This is a complete fictional UTF-8 text exercise for macOS, not a user-directory renamer. It uses Python 3.9 or later with the standard library and Darwin `renameatx_np`; the recorded runtime is Python 3.9.6 / macOS 26.5.2 arm64 / APFS, with case-insensitive lookup observed locally.

## Download the complete kit

Keep these files together in a new folder. All are supplied in this directory; no external package installation is needed.

- Inputs: [source-packet.zip](/blog/assets/content-based-file-naming-packet/shared/source-packet.zip), [input-inventory.csv](/blog/assets/content-based-file-naming-packet/shared/input-inventory.csv), [field-evidence.csv](/blog/assets/content-based-file-naming-packet/shared/field-evidence.csv).
- Decisions: [naming-rules.md](/blog/assets/content-based-file-naming-packet/en/naming-rules.md), [rename-plan.csv](/blog/assets/content-based-file-naming-packet/shared/rename-plan.csv), [wrong-plan.csv](/blog/assets/content-based-file-naming-packet/shared/wrong-plan.csv), [complete-request.txt](/blog/assets/content-based-file-naming-packet/en/complete-request.txt).
- Programs: [rename_packet.py](/blog/assets/content-based-file-naming-packet/shared/rename_packet.py), [reproduce.py](/blog/assets/content-based-file-naming-packet/shared/reproduce.py).
- Additional authored edge-case plans used by the reproduction: [duplicate-plan.csv](/blog/assets/content-based-file-naming-packet/shared/duplicate-plan.csv), [extension-plan.csv](/blog/assets/content-based-file-naming-packet/shared/extension-plan.csv), [outside-plan.csv](/blog/assets/content-based-file-naming-packet/shared/outside-plan.csv). Identity regression plans: [same-plan-with-blank-line.csv](/blog/assets/content-based-file-naming-packet/shared/same-plan-with-blank-line.csv) and [related-changed-plan.csv](/blog/assets/content-based-file-naming-packet/shared/related-changed-plan.csv).
- Recorded final-run output: [renamed-copy.zip](/blog/assets/content-based-file-naming-packet/shared/renamed-copy.zip), [applied-results.csv](/blog/assets/content-based-file-naming-packet/shared/applied-results.csv), [reversal-plan.csv](/blog/assets/content-based-file-naming-packet/shared/reversal-plan.csv), [conflicts.csv](/blog/assets/content-based-file-naming-packet/shared/conflicts.csv).

The source ZIP has all eight original documents. The renamed ZIP has all eight resulting documents: four renamed and four retained under their original names. Inventory and results provide each ID, name, exact bytes and SHA-256. Fields were checked by the author; no separate model extraction trial, OCR test or efficiency comparison was run.

## Inspect and try it

From your copy of the kit:

```sh
python3 rename_packet.py preview --plan wrong-plan.csv
python3 rename_packet.py preview --plan rename-plan.csv
python3 rename_packet.py init /private/tmp/fw1-reader-one
python3 rename_packet.py apply /private/tmp/fw1-reader-one
python3 rename_packet.py apply /private/tmp/fw1-reader-one
python3 rename_packet.py reverse /private/tmp/fw1-reader-one
```

Choose an unused `fw1-...` name; initialization refuses any existing directory. All paths affected by the helper are explicit fixture basenames inside the directory it creates. It does not scan user folders or recursively process files. Keep other programs from editing this private exercise. Never repoint it at real documents.

Read returned rows, not just the process exit. A completed evaluation returns 0 even if some rows are blocked or unknown; invalid invocations return 2. Unresolved history is checked by stable source ID inside the packet-bound owned directory, irrespective of plan bytes or replacement target. It takes precedence over plan-row rejection. Confirmed completion is separately tied to the stable source and exact old-to-target operation, with current-byte checks; the audit plan hash is not used to hide unknown history. Wrong-plan rows are all blocked. The correct plan changes F01/F02/F05/F07 and holds the other four. Repeat checks current bytes and confirmed journal results. Reverse checks the current target and blocks existing original names. An unknown stops subsequent rows. There is no automatic rollback, batch atomicity or recovery guarantee for interruption.

The short manual sequence leaves your teaching directory available for inspection. Remove your own `fw1-reader-one` directory only when finished. The automatic exercise below cleans up its own newly created roots.

## Reproduce the full recorded exercise

```sh
python3 reproduce.py
```

This creates two fresh source copies and ten case groups in twelve private roots. It checks every output file's name, bytes and hash, tests repeat and reverse behavior, preserves the frozen source archive, captures the renamed output, and removes only roots created by that invocation. It rewrites generated evidence beside the script; run it in another kit copy to preserve the supplied records.

The retained author run contains all 38 helper commands and their returned rows. Its raw execution wrapper is retained internally rather than supplied as a reader download. This is an author exercise, not an independent run or a replay of old directories. The pending-intent case is an authored interruption marker, not a crash or power-loss experiment. The recorded filesystem type came from a matching native mount record after `diskutil` returned 1, rather than from the OS name.

## Authorship and evidence scope

The tutorial and implementation share the same author. The recorded exercise uses fictional workshop notes and only the narrow local runtime described above. Execution timestamps are UTC; they are not article publication or modification dates. Download the original programs and data without changing their filenames or bytes.