@udondan/avanti 0.24.0 → 0.25.0

package/README.md

@@ -16,28 +16,45 @@ atomic rollbacks, and diff-before-apply safety.
   - [`avanti diff`](#avanti-diff)
   - [`avanti pull`](#avanti-pull)
   - [`avanti lock`](#avanti-lock)
+  - [`--verbose` / `-v`](#--verbose---v)
 - [History](#history)
   - [`avanti log`](#avanti-log)
   - [`avanti diff <pullId>`](#avanti-diff-pullid)
   - [`avanti revert [pullId]`](#avanti-revert-pullid)
   - [`avanti reset`](#avanti-reset)
-  - [`--verbose` / `-v`](#--verbose---v)
 - [Working Directory](#working-directory)
   - [Path Constraints](#path-constraints)
 - [Configuration](#configuration)
   - [File Entry Fields](#file-entry-fields)
   - [Source Types](#source-types)
+    - [SHA pinning](#sha-pinning)
+    - [Filter](#filter)
+    - [Extract](#extract)
   - [Directory Sources](#directory-sources)
   - [JSON Merging](#json-merging)
   - [YAML Merging](#yaml-merging)
   - [TOML Merging](#toml-merging)
+  - [INI Merging](#ini-merging)
   - [Template Rendering](#template-rendering)
+  - [Event Hooks](#event-hooks)
   - [Insert Mode](#insert-mode)
   - [Conditions](#conditions)
+    - [Condition fields](#condition-fields)
+    - [Examples](#examples)
   - [Scaffold Pattern](#scaffold-pattern)
   - [Backup](#backup)
+    - [Path variables](#path-variables)
+    - [Counter pattern](#counter-pattern)
+    - [Security: backup_roots](#security-backup_roots)
+    - [Backup examples](#backup-examples)
   - [Write in Place](#write-in-place)
+  - [Follow Symlink](#follow-symlink)
+  - [Sudo](#sudo)
   - [Variables](#variables)
+    - [List and object variables](#list-and-object-variables)
+    - [Accessing nested values with \${expr}](#accessing-nested-values-with-expr)
+    - [Source-based variables](#source-based-variables)
+    - [System-injected variables](#system-injected-variables)
   - [$self — Self-managing Config](#self--self-managing-config)
   - [Authentication](#authentication)
   - [Private Instances](#private-instances)
@@ -105,9 +122,10 @@ avanti revert  # roll back instantly if something breaks
 - **JSON merging** — deep-merge multiple JSON/JSONC sources with configurable conflict, array, and object strategies; format output with configurable indentation, trailing commas, key sorting, minification, and comment stripping
 - **YAML merging** — deep-merge multiple YAML/YML sources with the same strategies, with full comment preservation
 - **TOML merging** — deep-merge multiple TOML sources with configurable conflict, array, and table strategies
+- **INI merging** — deep-merge multiple INI/CFG sources with the same strategies, with full comment and key-order preservation
 - **Variables** — define reusable values in a `variables:` block and reference them anywhere with `$name`; variables can be plain strings, `$env:NAME` environment variable references, or fetched from any remote/local source (the same source types as `files:`)
 - **Post-processing** — apply text replacements (string or regex) and/or pipe content through a shell script
-- **Release artifacts** — download release assets attached to a GitHub or GitLab release by tag, or use `$latest` for the newest release (GitLab prefers `package`-type links; falls back to all links)
+- **Release artifacts** — download release assets attached to a GitHub or GitLab release by tag, `$latest` (newest stable semver tag), `$recent` (most recently created/published tag), or `/pattern/[flags]` (GitLab prefers `package`-type links; falls back to all links)
 - **Directory sync** — recursively sync directories from GitLab/GitHub/Bitbucket/git/S3/local sources
 - **SHA pinning** — pin any remote source to a content fingerprint with `sha:`; use `avanti lock` to compute and write SHAs automatically; `avanti pull --accept-changes` reviews a mismatch and updates the pin
 - **`$self`** — avanti can manage its own config file; declare `$self` in `files:` and the fetched content becomes the active config for the rest of the run, including YAML/JSON merge from multiple sources
@@ -188,10 +206,30 @@ Run `avanti pull --accept-changes` to review the diff and update SHA values.
 
 `avanti diff` shows a `⚠ SHA mismatch` warning inline for any source that no longer matches its pinned SHA.
 
-SHA is computed over the raw fetched content of each source, before any `replace` or `post` processing. Each file's path and content are fed into the hash in sorted order, separated by null bytes — so renames and additions affect the fingerprint even for single-file sources. Pull history records the observed SHA for every source, so `avanti log` shows a full audit trail of what changed and when.
+SHA is computed over the raw fetched content of each source, before any `replace` or `on.write` processing. Each file's path and content are fed into the hash in sorted order, separated by null bytes — so renames and additions affect the fingerprint even for single-file sources. Pull history records the observed SHA for every source, so `avanti log` shows a full audit trail of what changed and when.
 
 Excluded from SHA pinning: local paths and `raw:` sources (their content is either authored locally or inline in the config, so changes are always visible).
 
+### `--verbose` / `-v`
+
+Pass `--verbose` (or `-v`) to any command to print internal debug details to stderr. Verbose output does not appear on stdout, so piping diff output is unaffected.
+
+```sh
+avanti diff --verbose
+avanti pull -v
+```
+
+Each line is prefixed with `[verbose]` and includes:
+
+- The source being fetched (e.g. `github:org/repo:file@main`)
+- Every HTTP request URL and response status code
+- Retry delays and reasons
+- CLI tool invocations (`gh`, `glab`, `vault`, `git`)
+- AWS SDK API calls (`s3 GetObject`, `ssm GetParameter`, `secrets-manager GetSecretValue`)
+- Cache hits
+
+**Credential safety:** tokens are read from environment variables and sent as HTTP headers, which are never logged. Git URLs with embedded credentials are redacted. `exec:` source commands are logged verbatim — if your config embeds secrets in an exec command (e.g. `exec: curl -H "Token: $env:MY_SECRET"`), those secrets will appear in verbose output after variable substitution.
+
 ## History
 
 Every successful `avanti pull` that writes at least one file is recorded in a local history store. This lets you inspect what changed, preview past states, revert the whole project, or fully undo all avanti changes.
@@ -287,31 +325,19 @@ Apply? [y/N]
 
 Use `--yes` to skip the prompt. The history log is preserved — you can still run `avanti log` after a reset.
 
-### `--verbose` / `-v`
-
-Pass `--verbose` (or `-v`) to any command to print internal debug details to stderr. Verbose output does not appear on stdout, so piping diff output is unaffected.
-
-```sh
-avanti diff --verbose
-avanti pull -v
-```
-
-Each line is prefixed with `[verbose]` and includes:
-
-- The source being fetched (e.g. `github:org/repo:file@main`)
-- Every HTTP request URL and response status code
-- Retry delays and reasons
-- CLI tool invocations (`gh`, `glab`, `aws`, `vault`, `git`)
-- Cache hits
-
-**Credential safety:** tokens are read from environment variables and sent as HTTP headers, which are never logged. Git URLs with embedded credentials are redacted. `exec:` source commands are logged verbatim — if your config embeds secrets in an exec command (e.g. `exec: curl -H "Token: $env:MY_SECRET"`), those secrets will appear in verbose output after variable substitution.
-
 ## Working Directory
 
 All relative `src` and `target` paths are resolved relative to the **working directory** — the directory where you invoke `avanti`, or the path given with `-w`.
 
 This is independent of where the config file lives. A config loaded from another directory with `-c /shared/avanti.yml` still resolves all paths from your working directory (or the one you specify with `-w`).
 
+The path given to `-w` supports tilde expansion: `~` resolves to the home directory and `~/some/path` resolves to a subdirectory of it:
+
+```sh
+avanti -w ~ pull              # home directory as working dir
+avanti -w ~/projects/foo pull # subdirectory of home
+```
+
 Use `-w` to deploy the same config to multiple locations without `cd`-ing there first:
 
 ```sh
@@ -360,7 +386,8 @@ files:
   some-file.yml:
     src:
       exec: glab api "projects/group%2Fproject/repository/files/some-file.yaml/raw?ref=main"
-    post: sed -e 's/v3/v4/g'
+    on:
+      write: sed -e 's/v3/v4/g'
 
   renovate.json:
     src:
@@ -407,19 +434,26 @@ A brace group is only expanded when it contains **at least one comma** (e.g. `{f
 
 > **YAML quoting:** YAML treats `{` at the start of a plain key as a flow mapping. If the brace group is the first character of a key, quote it: `'{dev,prod}.yml':` or `"{dev,prod}.yml":`. Keys where the brace group appears after a path prefix (e.g. `config/{dev,prod}.yml`) do not need quoting.
 
-| Field          | Required | Description                                                                                                                                                                                                                             |
-| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src`          | Yes      | Source (see below). May be a single source or a **list** of sources to concatenate.                                                                                                                                                     |
-| `if`           | No       | Condition object (or list of objects). All must pass for the entry to be processed. See [Conditions](#conditions).                                                                                                                      |
-| `ifAny`        | No       | List of condition objects. At least one must pass. See [Conditions](#conditions).                                                                                                                                                       |
-| `mode`         | No       | File permission mode. Use a quoted octal string (`"0755"`) or a YAML octal literal (`0o755`). Mode-only changes (content unchanged) are detected by `diff` and applied by `pull`. **POSIX only** — ignored on Windows.                  |
-| `replace`      | No       | List of `{from, to}` replacement rules. `from` may be a plain string or `/pattern/flags` regex.                                                                                                                                         |
-| `post`         | No       | Shell script. Content is piped via stdin; stdout is used as the result. Runs after `replace`.                                                                                                                                           |
-| `template`     | No       | Treat the fetched content as a template and render it with avanti config variables as context. See [Template Rendering](#template-rendering).                                                                                           |
-| `json`         | No       | JSON merge/format options (see below). When omitted, merging is auto-enabled if all sources have a `.json` or `.jsonc` extension. Use `true`/`false` to force on or off regardless of extension.                                        |
-| `yaml`         | No       | YAML merge/format options (see below). When omitted, merging is auto-enabled if all sources have a `.yaml` or `.yml` extension. Use `true`/`false` to force on or off regardless of extension. Comments are preserved in merged output. |
-| `strategy`     | No       | Write strategy: `replace` _(default)_ — overwrite the target file entirely; `insert` — merge content into the existing file without clobbering unrelated content. See [Insert Mode](#insert-mode).                                      |
-| `writeInPlace` | No       | If `true`, replaces file content in-place instead of using an atomic rename. Preserves the existing inode. **Not atomic** — use only when inode stability is required. See [Write in Place](#write-in-place).                           |
+| Field           | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`           | Yes      | Source (see below). May be a single source or a **list** of sources to concatenate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `if`            | No       | Condition object (or list of objects). All must pass for the entry to be processed. See [Conditions](#conditions).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `ifAny`         | No       | List of condition objects. At least one must pass. See [Conditions](#conditions).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `mode`          | No       | File permission mode. Use a quoted octal string (`"0755"`) or a YAML octal literal (`0o755`). Mode-only changes (content unchanged) are detected by `diff` and applied by `pull`. **POSIX only** — ignored on Windows.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `backup`        | No       | Path to copy the current file to before overwriting it. Supports path variables (`$dirname`, `$filename`, `$datetime`) and the `%d+` counter token for auto-incrementing slots. See [Backup](#backup).                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `replace`       | No       | List of `{from, to}` replacement rules. `from` may be a plain string or `/pattern/flags` regex.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `on`            | No       | Lifecycle event hooks. See [Event Hooks](#event-hooks).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `template`      | No       | Treat the fetched content as a template and render it with avanti config variables as context. See [Template Rendering](#template-rendering).                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `json`          | No       | JSON merge/format options (see below). When omitted, merging is auto-enabled if all sources have a `.json` or `.jsonc` extension. Use `true`/`false` to force on or off regardless of extension.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `yaml`          | No       | YAML merge/format options (see below). When omitted, merging is auto-enabled if all sources have a `.yaml` or `.yml` extension. Use `true`/`false` to force on or off regardless of extension. Comments are preserved in merged output.                                                                                                                                                                                                                                                                                                                                                                             |
+| `toml`          | No       | TOML merge/format options (see below). When omitted, merging is auto-enabled if all sources have a `.toml` extension. Use `true`/`false` to force on or off regardless of extension. See [TOML Merging](#toml-merging).                                                                                                                                                                                                                                                                                                                                                                                             |
+| `ini`           | No       | INI merge/format options (see below). When omitted, merging is auto-enabled if all sources have a `.ini` or `.cfg` extension. Use `true`/`false` to force on or off regardless of extension. Comments and key order are preserved. See [INI Merging](#ini-merging).                                                                                                                                                                                                                                                                                                                                                 |
+| `strategy`      | No       | Write strategy: `replace` _(default)_ — overwrite the target file entirely; `insert` — merge content into the existing file without clobbering unrelated content. See [Insert Mode](#insert-mode).                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `writeInPlace`  | No       | If `true`, replaces file content in-place instead of using an atomic rename. Preserves the existing inode. **Not atomic** — use only when inode stability is required. Errors if the target is a symlink. See [Write in Place](#write-in-place).                                                                                                                                                                                                                                                                                                                                                                    |
+| `followSymlink` | No       | If `true` and the target path is a symlink, writes the fetched content to the **symlink's target** instead of replacing the symlink itself. The resolved target must not be a directory and must stay inside the working directory. See [Follow Symlink](#follow-symlink).                                                                                                                                                                                                                                                                                                                                          |
+| `symlink`       | No       | Create a symlink at the target path instead of writing file content. `src` must be a single local path. Use `true` or `"absolute"` to create an absolute symlink; use `"relative"` to express the symlink target as a path relative to the symlink's parent directory. Cannot be combined with `replace`, `template`, `json`, `yaml`, `toml`, `ini`, `on.write`, `extract`, `writeInPlace`, `strategy`, `followSymlink`, `mode`, or a list `src`. See [Symlink](#symlink).                                                                                                                                          |
+| `extract`       | No       | Unpack an archive (`.zip`, `.tar`, `.tar.gz`, `.tgz`) downloaded from a single-file source before writing. Target must end with `"/"`. Use `true` to extract all files, or a list of patterns to extract only matching entries. Cannot be combined with a list `src`. See [Extract](#extract).                                                                                                                                                                                                                                                                                                                      |
+| `sudo`          | No       | Write the file using elevated privileges. Use `true` to write as root, or a username string (e.g. `"www-data"`) to write as a specific user via `sudo -u`. avanti authenticates once per distinct identity before any writes — the OS sudo credential cache is reused for all subsequent operations within the same pull session. **POSIX only** — `pull` errors on Windows when any file has `sudo` set. **Note:** `sudo` is honored by `pull` only (including stale-file cleanup). The `revert` and `reset` commands restore files using normal (non-elevated) file operations and will fail on root-owned paths. |
 
 ### Source Types
 
@@ -461,7 +495,7 @@ src:
   gitlab:
     project: group/repo          # GitLab project path
     file: path/to/file.txt       # file or directory in repo (mutually exclusive with release)
-    ref: main                    # branch, tag, or $latest (optional)
+    ref: main                    # branch, tag, $latest, $recent, or /pattern/ (optional)
     sha: abc123...               # optional SHA-256 fingerprint
     host: gitlab.mycompany.com   # override default gitlab.com (optional)
     via: cli                     # api, cli, or list (default: [api, cli])
@@ -470,16 +504,19 @@ src:
 src:
   gitlab:
     project: group/repo          # GitLab project path
-    release: v1.2.3              # release tag, or $latest (mutually exclusive with file)
+    release: v1.2.3              # release tag, $latest, $recent, or /pattern/ (mutually exclusive with file)
     sha: abc123...               # optional SHA-256 fingerprint
     host: gitlab.mycompany.com   # override default gitlab.com (optional)
     via: cli                     # api, cli, or list (default: [api, cli])
+  filter:                        # optional: keep only matching assets (see below)
+    - installer.deb
+    - checksums-{amd64,arm64}.txt
 
 src:
   github:
     repo: owner/repo             # GitHub owner/repo
     file: path/to/file.txt       # file or directory in repo (mutually exclusive with release)
-    ref: main                    # branch, tag, or $latest (optional)
+    ref: main                    # branch, tag, $latest, $recent, or /pattern/ (optional)
     sha: abc123...               # optional SHA-256 fingerprint
     host: github.mycompany.com   # GitHub Enterprise Server hostname (optional)
     via: cli                     # api, cli, or list (default: [api, cli])
@@ -488,10 +525,14 @@ src:
 src:
   github:
     repo: owner/repo             # GitHub owner/repo
-    release: v1.2.3              # release tag, or $latest (mutually exclusive with file)
+    release: v1.2.3              # release tag, $latest, $recent, or /pattern/ (mutually exclusive with file)
     sha: abc123...               # optional SHA-256 fingerprint
     host: github.mycompany.com   # GitHub Enterprise Server hostname (optional)
     via: cli                     # api, cli, or list (default: [api, cli])
+  filter:                        # optional: keep only matching assets (see below)
+    - exact-match.png
+    - file-{a,b,c}.yml
+    - /^some.*\.jpg/
 
 src:
   bitbucket:
@@ -547,6 +588,79 @@ The optional `sha` field pins a source to a specific content fingerprint. When p
 
 Use `avanti lock` to compute and write SHA values automatically. Use `avanti pull --accept-changes` to review a mismatch and update the pinned SHA. Plain string sources (a bare local path or URL string) and `raw:` sources do not support `sha`. Use the explicit `path:` or `url:` map form to pin a local file or HTTP URL.
 
+#### Filter
+
+The optional `filter` field narrows which files are kept when a source returns multiple files (directory sources, release artifacts, S3 prefixes). It is supported on `path:`, `github:`, `gitlab:`, `bitbucket:`, `git:`, and `aws_s3:` sources.
+
+`filter` is a list of one or more patterns. A file is kept if **any** pattern matches its path relative to the source root (the filename for flat sources like release assets, or the relative path for directory sources). Paths are always matched using forward slashes (`/`) regardless of the platform — on Windows, write `subdir/file.yml`, not `subdir\file.yml`.
+
+| Pattern            | Matches                                                                                |
+| ------------------ | -------------------------------------------------------------------------------------- |
+| `exact.png`        | Exact string equality                                                                  |
+| `subdir/`          | Directory prefix — all entries whose path starts with `subdir/`                        |
+| `file-{a,b,c}.yml` | Brace-expanded alternatives — `file-a.yml`, `file-b.yml`, `file-c.yml`                 |
+| `/^some.*\.jpg/`   | JavaScript regular expression (delimited by `/`) tested against the full relative path |
+
+```yaml
+files:
+  assets/:
+    src:
+      github:
+        repo: owner/repo
+        release: $latest
+      filter:
+        - exact-match.png
+        - dist/ # all files under dist/
+        - checksums-{amd64,arm64}.txt
+        - /^some.*\.jpg/
+```
+
+Variables are resolved in filter patterns before matching, so patterns like `$env:ARCH.tar.gz` or `$platform-release.zip` work as expected. An error is raised if the filter matches zero files, preventing silent misconfiguration. The `sha` fingerprint (if present) is computed over the filtered set.
+
+> **Note:** brace expansion is not supported in directory-prefix patterns (patterns ending with `/`). Use separate patterns instead — e.g. `"core/"` and `"utils/"` rather than `"{core,utils}/"`.
+
+#### Extract
+
+The optional `extract` field unpacks a downloaded archive before writing files. It applies to any single-file source (HTTP URL, local path, etc.) that returns an archive. Set `extract: true` to extract all entries, or provide a list of patterns to keep only matching entries.
+
+**The target must be a directory** (end with `/`). Archive extraction writes multiple files; a non-directory target is rejected at parse time.
+
+| Format     | Extensions        |
+| ---------- | ----------------- |
+| ZIP        | `.zip`            |
+| tar        | `.tar`            |
+| tar + gzip | `.tar.gz`, `.tgz` |
+
+Patterns use the same syntax as [`filter`](#filter):
+
+| Pattern       | Matches                                                                                |
+| ------------- | -------------------------------------------------------------------------------------- |
+| `exact.png`   | Exact string equality                                                                  |
+| `subdir/`     | Directory prefix — all entries whose path starts with `subdir/`                        |
+| `{a,b,c}.yml` | Brace-expanded alternatives                                                            |
+| `/^.*\.jpg/`  | JavaScript regular expression (delimited by `/`) tested against the full relative path |
+
+> **Note:** brace expansion is not supported in directory-prefix patterns (patterns ending with `/`). Use separate patterns instead — e.g. `"core/"` and `"utils/"` rather than `"{core,utils}/"`.
+
+```yaml
+files:
+  # Extract all files from a release archive into a local directory
+  tools/:
+    src: https://example.com/release.tar.gz
+    extract: true
+
+  # Extract only matching entries
+  assets/:
+    src: https://example.com/bundle.zip
+    extract:
+      - readme.md # exact match
+      - images/ # all entries under images/
+      - libs/{core,utils}.js # brace expansion (not with trailing /)
+      - /^assets\/.*\.png$/ # regex
+```
+
+Variables are resolved in patterns before matching. An error is raised if the pattern list matches zero entries. `extract` cannot be combined with a list `src`. Entry paths are validated — archives containing path-traversal sequences (`../`) or absolute paths are rejected for security. The `sha` fingerprint (if present) is computed over the archive before extraction.
+
 ### Directory Sources
 
 Any source type that references a path (local, GitLab, GitHub, Bitbucket, git, S3) can point to a directory instead of a single file. End the path with `/` to declare it a directory explicitly; without a trailing slash the tool probes the remote to decide.
@@ -637,7 +751,7 @@ files:
           ref: main
 ```
 
-Sources are fetched in order and joined with a newline. Post-processing (`replace`, `post`) is applied to the combined result. If any source fails, the entire entry is aborted.
+Sources are fetched in order and joined with a newline. Post-processing (`replace`, `on.write`) is applied to the combined result. If any source fails, the entire entry is aborted.
 
 ### JSON Merging
 
@@ -844,11 +958,111 @@ files:
     src: ./config.toml
 ```
 
+### INI Merging
+
+When all sources in a list have a `.ini` or `.cfg` extension, INI merging is enabled
+automatically — no extra config needed:
+
+```yaml
+files:
+  merged.ini:
+    src:
+      - ./defaults.ini
+      - ./overrides.ini
+```
+
+To merge sources that don't have an INI extension (e.g. `exec:`, `raw:`, or a URL without `.ini`), set `ini: true`:
+
+```yaml
+files:
+  merged.ini:
+    src:
+      - exec: cat defaults.ini
+      - ./overrides.ini
+    ini: true
+```
+
+To opt out of auto-detection and force plain concatenation, set `ini: false`.
+
+**Fine-grained options** — pass an object to control merge behavior:
+
+```yaml
+files:
+  merged.ini:
+    src:
+      - ./defaults.ini
+      - github:
+          repo: org/configs
+          file: overrides.ini
+    ini:
+      conflicts: last_wins # abort | first_wins | last_wins (default)
+      arrays: replace # replace (default) | concat | dedupe
+      objects: merge # merge (default) | replace
+```
+
+The options behave identically to JSON, YAML, and TOML merging:
+
+- `conflicts` — what to do when the same key holds a scalar (or an array/object when their strategy is `replace`):
+  - `last_wins` _(default)_ — the last source's value wins
+  - `first_wins` — the first source's value is kept
+  - `abort` — throw an error (identical values are not considered a conflict)
+- `arrays` — how to combine arrays at the same key (written as `key[] = val` in INI):
+  - `replace` _(default)_ — the later source's array replaces the earlier one
+  - `concat` — arrays are concatenated (no deduplication)
+  - `dedupe` — items from the later source are appended only if not already present
+- `objects` — how to combine sections at the same name:
+  - `merge` _(default)_ — deep merge, applying the same rules recursively to section keys
+  - `replace` — the later source's section replaces the earlier one entirely
+
+**Comments and key order are preserved in the base (first) source.** The INI processor uses
+a line-level AST, so comment lines, inline comments, and blank lines from the first source
+are preserved through the merge. Minor whitespace normalization may occur (e.g. a single
+space is inserted before inline comments, and spacing around `=` follows the base key's
+original separator). When a key's value is updated by a later source, the base key's inline
+comment is kept and the key stays at its original position — it is not shuffled to the end.
+**Comment behavior under `objects: merge` (default):** Comment lines (`; ...` / `# ...`),
+blank lines, and section header comments from overlay sources are not transferred when merging
+individual keys. For keys that already exist in the base, the base key's inline comment is
+kept. For new keys introduced only by the overlay, their inline comments are preserved (there
+is no base inline comment to fall back on). When a new section is introduced by the overlay
+(one that does not exist in the base), it is inserted without its section header comment or
+any internal comment/blank nodes — only its key-value pairs are carried over.
+
+**Comment behavior under `objects: replace`:** When the overlay section's key-value content
+differs from the base, the entire overlay section is used as-is — including its section
+header comment, internal comment lines, blank lines, and inline comments. If the two sections
+have identical key-value content (even when they differ only in comments or whitespace), no
+replacement occurs — the base section is kept unchanged.
+
+**Inline comment limitation for arrays:** When the same key appears as multiple `key[] = val`
+entries, all values are coalesced into a single array node. Only the inline comment from the
+_first_ occurrence (if any) is preserved; inline comments on subsequent `key[] = val` lines are
+discarded.
+
+**Supported INI features:** sections (`[section]`), subsections (`[section "name"]`),
+`key = value` pairs, bare keys, quoted values (`"..."` / `'...'`), comment lines (`;` and `#`),
+inline comments, blank lines, backslash line continuation, and arrays via `key[] = val`. All
+`key[] = val` entries for the same key are collected into one array regardless of position in
+the file; non-contiguous entries are normalized to appear at the first occurrence of that key.
+
+**Value coercion:** Unquoted values that match `true` or `false` (case-insensitive) are parsed
+as booleans, and values that parse as a valid number are parsed as numbers. This means
+`enabled = true` is stored as a boolean and `port = 8080` as a number; on format or merge
+these are re-serialised as `true` / `8080` respectively. Strings like `001` are normalised to
+`1`. To preserve the exact string form, quote the value: `port = "8080"`.
+
+**Inline comment delimiter:** `;` and `#` are treated as comment delimiters when they appear
+outside of quoted strings. If a value contains a literal `;` or `#` character, quote the value
+(e.g. `url = "https://example.com#anchor"`) to prevent it from being interpreted as a comment.
+
+**Pretty-printing a single file** — `ini` works on single-source entries too. Auto-detection
+applies here as well, so a single `.ini` or `.cfg` source is normalized automatically.
+
 ### Template Rendering
 
 Set `template` to treat the fetched content as a template. avanti renders it at deploy time using all avanti config variables as the template context, then writes the rendered output to the target file.
 
-> **Security note** — EJS and Eta templates execute arbitrary JavaScript at render time. Handlebars, Nunjucks, Liquid, and Mustache are logic-limited and do not execute raw JS. For any engine, template sources must be trusted: either authored locally, fetched from a controlled internal source, or SHA-pinned (see [`sha:`](#sha-pinning)). Treat a compromised remote template as equivalent to a compromised `post:` script or `exec:` source.
+> **Security note** — EJS and Eta templates execute arbitrary JavaScript at render time. Handlebars, Nunjucks, Liquid, and Mustache are logic-limited and do not execute raw JS. For any engine, template sources must be trusted: either authored locally, fetched from a controlled internal source, or SHA-pinned (see [`sha:`](#sha-pinning)). Treat a compromised remote template as equivalent to a compromised `on.write` script or `exec:` source.
 
 ```yaml
 variables:
@@ -889,7 +1103,42 @@ For multi-source arrays (`src: [a, b, c]`) and directory-to-single-file merges,
 
 **`jinja2` alias** — `template: jinja2` is equivalent to `template: nunjucks`. Nunjucks is a JavaScript implementation heavily inspired by Jinja2; most Jinja2 templates work without changes.
 
-**Pipeline order** — template rendering runs first, before `replace` and `post`. Subsequent processors receive the already-rendered content.
+**Pipeline order** — template rendering runs first, before `replace` and `on.write`. Subsequent processors receive the already-rendered content.
+
+### Event Hooks
+
+The `on:` field on a file entry lets you run shell commands at specific points in the file lifecycle. `on.write` supports avanti variable substitution (same rules as `exec:` and `replace:`). Side-effect hooks (`before*`, `create`, `update`) are passed to the shell verbatim — use `$AVANTI_TARGET` and `$AVANTI_IS_NEW` as environment variables.
+
+| Hook              | When                                                                            | Content transform? |
+| ----------------- | ------------------------------------------------------------------------------- | ------------------ |
+| `on.write`        | During processing, after `replace`; stdin → stdout replaces content             | Yes                |
+| `on.beforeWrite`  | After user confirms, before writing — fires for every changed file              | No                 |
+| `on.beforeCreate` | Same timing, but only when the file is being **created** for the first time     | No                 |
+| `on.beforeUpdate` | Same timing, but only when the file already **exists** and has changed          | No                 |
+| `on.create`       | After the file has been successfully written — new files only                   | No                 |
+| `on.update`       | After the file has been successfully written — existing files with changes only | No                 |
+
+Side-effect hooks (`before*`, `create`, `update`) receive two environment variables:
+
+| Variable        | Value                                                       |
+| --------------- | ----------------------------------------------------------- |
+| `AVANTI_TARGET` | Absolute path of the target file                            |
+| `AVANTI_IS_NEW` | `"true"` if the file is being created; `"false"` if updated |
+
+On Unix, access them as `$AVANTI_TARGET` / `$AVANTI_IS_NEW`. On Windows (PowerShell), avanti automatically injects a prelude that maps these to local variables, so `$AVANTI_TARGET` works identically — you do not need to write `$env:AVANTI_TARGET`.
+
+Only hooks for files with **actual changes** are fired (`create`/`update`/`before*` are silent no-ops when content and mode are unchanged).
+
+```yaml
+files:
+  config/app.yml:
+    src: https://config.example.com/app.yml
+    on:
+      write: sed -e 's/v3/v4/g' # transform content
+      beforeCreate: mkdir -p "$(dirname "$AVANTI_TARGET")"
+      create: echo "Created $AVANTI_TARGET"
+      update: git add "$AVANTI_TARGET"
+```
 
 ### Insert Mode
 
@@ -906,7 +1155,7 @@ files:
 **How it works:**
 
 - **First run** — the fetched content is merged into the existing file (or written as-is if the file does not exist yet).
-- **Subsequent runs (no-op)** — avanti detects that the raw source and the post-processed output (`replace`/`post`) are both unchanged and skips the file entirely.
+- **Subsequent runs (no-op)** — avanti detects that the raw source and the post-processed output (`replace`/`on.write`) are both unchanged and skips the file entirely.
 - **Subsequent runs (source changed)** — avanti removes the keys/text it previously contributed, then merges the updated content in.
 - **User edits are preserved** — keys or text the user added or modified are left untouched. If a user overrides an avanti-managed key, avanti will not remove it even if the source no longer includes it.
 
@@ -944,13 +1193,13 @@ When both are present, both must pass. Each condition object may also include `n
 
 #### Condition fields
 
-| Field           | Type           | Description                                                                        |
-| --------------- | -------------- | ---------------------------------------------------------------------------------- |
-| `os`            | string or list | Platform must match. Values: `linux`, `mac`, `windows`. List = any matches.        |
-| `exists`        | string         | Path (file or directory) must exist. Variables are resolved.                       |
-| `exec`          | string         | Shell command must exit with code `0`.                                             |
-| `target_exists` | boolean        | `true` — pass only if target exists. `false` — pass only if target does not exist. |
-| `not`           | boolean        | `true` — invert the result of all checks in this condition object.                 |
+| Field           | Type           | Description                                                                                                                     |
+| --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `os`            | string or list | Platform must match. Values: `linux`, `mac`, `windows`. Aliases: `darwin` (= `mac`), `win32` (= `windows`). List = any matches. |
+| `exists`        | string         | Path (file or directory) must exist. Variables are resolved.                                                                    |
+| `exec`          | string         | Shell command must exit with code `0`.                                                                                          |
+| `target_exists` | boolean        | `true` — pass only if target exists. `false` — pass only if target does not exist.                                              |
+| `not`           | boolean        | `true` — invert the result of all checks in this condition object.                                                              |
 
 #### Examples
 
@@ -1063,11 +1312,11 @@ files:
     backup: $dirname/$filename.bkp
 ```
 
-Backup only happens when the target is a regular file (not a symlink or directory). If the backup path already exists it is overwritten — use the [counter pattern](#counter-pattern) or `$datetime` when you want to keep every backup.
+Backup happens when the target path currently holds a regular file or a symlink — regardless of whether the entry being written is a regular file or a symlink entry. On POSIX, if the existing target is a symlink, the symlink itself (not the file it points to) is preserved in the backup; if the symlink had a relative target, avanti rewrites it to an absolute path so the backup symlink resolves correctly from the backup directory. On Windows, symlink backups are skipped (a warning is printed) because creating a symlink backup requires elevated privileges and dereferencing the link could read files outside the working directory. **Exception:** for regular-file entries with `sudo: true`, only existing regular files are backed up — if the current target is a symlink it is not backed up. For `symlink:` entries with `sudo: true`, the existing symlink (or regular file) at the target path is backed up before being replaced. Directory targets are never backed up. If the backup path already exists it is overwritten — use the [counter pattern](#counter-pattern) or `$datetime` when you want to keep every backup.
 
 #### Path variables
 
-All [system-injected variables](#system-injected-variables) — per-file path variables (`$path`, `$filename`, `$basename`, `$ext`, `$dirname`, `$basedir`) and pull-time variables (`$date`, `$datetime`) — are available in `backup:` patterns.
+All [system-injected variables](#system-injected-variables) — per-file path variables (`$path`, `$filename`, `$basename`, `$ext`, `$dirname`, `$basedir`), pull-time variables (`$date`, `$datetime`), and system variables (`$os`, `$arch`, `$arch_go`) — are available in `backup:` patterns.
 
 #### Counter pattern
 
@@ -1149,6 +1398,111 @@ files:
 
 > **Warning:** `writeInPlace: true` is **not atomic**. Between the truncate and the completed write, a concurrent reader will see empty or partial content. Use the default atomic rename when correctness under concurrent reads matters more than inode stability.
 
+### Follow Symlink
+
+When the target path is a symlink, avanti's default atomic-rename strategy replaces the symlink itself — the symlink is overwritten with the fetched file content. Set `followSymlink: true` to write through the symlink instead: avanti resolves the symlink chain to its real path and writes the content there, leaving the symlink pointer intact.
+
+> **Interaction with `writeInPlace`:** `writeInPlace: true` errors when its target path is a symlink. When combined with `followSymlink: true`, avanti resolves the symlink first and passes the real path to the writer, so `writeInPlace` never sees a symlink. The result: content is written in-place to the real file (inode preserved) while the symlink itself remains intact.
+
+```yaml
+files:
+  config/settings.json:
+    src:
+      github:
+        repo: org/shared-configs
+        file: settings.json
+    followSymlink: true
+```
+
+This is useful when a symlink is managed by another tool (e.g. a dotfile manager) and must not be replaced. avanti updates the real file's content while the symlink pointer remains unchanged.
+
+**Safety constraints** — avanti validates the resolved target before writing:
+
+- The resolved path must **not be a directory** — avanti refuses to write file content over a directory target.
+- The resolved path must remain **inside the working directory** — symlinks that escape (directly or through intermediate symlinked directories) are rejected.
+- **Circular symlinks** are detected and rejected.
+
+Dangling symlinks (a symlink chain whose endpoint does not yet exist) are supported: avanti follows the chain to the non-existent endpoint and creates the file there, subject to the same directory and working-directory constraints above.
+
+When the target path does not exist yet, or does not point to a symlink, `followSymlink` has no effect and the file is created or written normally.
+
+### Symlink
+
+Set `symlink: true` (or `symlink: "absolute"`) to create a filesystem symlink at the target path pointing to the `src` path, instead of copying the file's content. The `src` must be a single local path — remote sources (HTTP, GitHub, GitLab, exec, etc.) are not supported.
+
+```yaml
+files:
+  ~/.config/app/config.yml:
+    src: /opt/app/defaults/config.yml
+    symlink: true
+```
+
+Use `symlink: "relative"` to store the symlink target as a path relative to the symlink's parent directory. This is useful when you want symlinks that remain valid after the directory tree is moved or mounted at a different location:
+
+```yaml
+files:
+  configs/active:
+    src: configs/production.yml
+    symlink: relative # symlink points to production.yml rather than an absolute path
+```
+
+**How `diff` and `pull` handle symlinks:**
+
+- No symlink at the target path → create it (shown as a new entry in the diff)
+- Symlink already points to the correct target → no-op (no diff output, exit 0)
+- Symlink points to a different target → update it (diff shows old → new target)
+- A regular file exists at the target path → replace it with a symlink (shown in diff)
+
+The symlink itself is tracked in avanti's history, so `revert` and `reset` restore the symlink (including its target path) to the state recorded at the referenced pull.
+
+**Constraints** — `symlink` cannot be combined with:
+
+- `replace`, `template`, `json`, `yaml`, `toml`, `ini`, `on.write`, `extract` — content processors are meaningless for a symlink
+- `writeInPlace`, `strategy`, `followSymlink` — incompatible write strategies
+- `mode` — symlinks do not have independent permission bits on POSIX
+- A list `src` — a symlink has exactly one target
+- `src.sha`, `src.filter`, `src.if`, `src.ifAny` — object-form src options that only apply to fetched content
+- The `$self` key — the config file itself cannot be a symlink entry
+
+**POSIX only** — symlink entries are not supported on Windows. `pull` will error if a symlink entry is reached on win32. Use an `if: { os: [linux, mac] }` condition to gate symlink entries in cross-platform configs.
+
+### Sudo
+
+Set `sudo: true` to write a file using elevated privileges (as root). Set `sudo: "username"` to write as a specific user via `sudo -u`:
+
+```yaml
+files:
+  /etc/ssh/sshd_config:
+    src:
+      github:
+        repo: org/system-configs
+        file: sshd_config
+    mode: '0600'
+    sudo: true
+
+  /var/www/html/index.html:
+    src: https://example.com/index.html
+    sudo: 'www-data'
+```
+
+Absolute target paths (e.g. `/etc/ssh/sshd_config`) require `--working-dir /`. The map key is the target path:
+
+```sh
+avanti pull --working-dir /
+```
+
+avanti calls `sudo -v` once per distinct identity to prime the OS credential cache, so the user is prompted for their password at most once per distinct sudo identity per pull session. Authentication happens as early as needed: if any sudo target is unreadable by the current user (e.g. a root-owned file), avanti authenticates before reading that file to compare it for the diff — so a password prompt may appear before the diff is displayed or the user is asked to confirm. For files that are already readable, authentication is deferred until just before the write phase.
+
+**Stale-file cleanup** — when a `sudo` entry is removed from the config, avanti uses the stored sudo identity to restore or delete the file during the next pull.
+
+**POSIX only** — `pull` errors on Windows when any file has `sudo` set. Use an `if: { os: [linux, mac] }` condition to gate `sudo` entries in cross-platform configs.
+
+**Limitations:**
+
+- `sudo` is honored by `pull` only. The `revert` and `reset` commands use normal file operations and will fail on root-owned paths.
+- `strategy: insert` cannot be combined with `sudo` — insert mode reads the existing file without privilege escalation, which silently treats an unreadable privileged file as absent. avanti rejects this combination at config parse time.
+- `backup` paths for `sudo` entries are resolved before privilege escalation. The backup path's parent directories must be stat-able by the current user (all ancestor directories need the execute/search bit set). A 0755 root-owned backup directory works fine; a 0700 root-owned directory does not, because `lstat` cannot traverse it to resolve `%d` counters or verify the path.
+
 ### Variables
 
 Define reusable values at the top level under `variables:`:
@@ -1174,11 +1528,11 @@ files:
         to: $email # resolved to "you@example.com"
 ```
 
-Variables are resolved in every string field: target keys, `ref`, `exec` commands, HTTP URLs, local paths, `raw` content, `replace` rules (`from` and `to`), and `post` scripts.
+Variables are resolved in every string field: target keys, `ref`, `exec` commands, HTTP URLs, local paths, `raw` content, `filter` patterns, `replace` rules (`from` and `to`), and `on.write` scripts. Side-effect hooks (`on.beforeWrite`, `on.beforeCreate`, `on.beforeUpdate`, `on.create`, `on.update`) are passed to the shell verbatim — use `$AVANTI_TARGET` / `$AVANTI_IS_NEW` env vars instead of `$varname` substitutions.
 
 For `raw:` sources, variables are resolved in the content itself. For all other source types (`http`, `local`, `github`, `gitlab`, `exec`), variables are only resolved in the fields that locate the source (URL, path, command) — not in the fetched content. Use a `replace:` rule if you need to substitute values in fetched content.
 
-**Shell safety in `exec:` and `post:`** — when a variable is substituted into an `exec:` command or a `post:` script, its value is automatically single-quoted. This means shell metacharacters (`;`, `&&`, `$(...)`, etc.) in the value are treated as literal data and are never executed. The surrounding command template itself is not quoted, so the static shell syntax you write is executed as usual. On Unix the script runs via `sh -c`; on Windows it runs via PowerShell (`-EncodedCommand`).
+**Shell safety in `exec:` and `on.write`** — when a variable is substituted into an `exec:` command or an `on.write` hook script, its value is automatically single-quoted. This means shell metacharacters (`;`, `&&`, `$(...)`, etc.) in the value are treated as literal data and are never executed. The surrounding command template itself is not quoted, so the static shell syntax you write is executed as usual. On Unix the script runs via `sh -c`; on Windows it runs via PowerShell (`-EncodedCommand`).
 
 ```yaml
 variables:
@@ -1188,10 +1542,11 @@ files:
   data.json:
     src:
       exec: curl https://example.com/api/$version/data # expands to: curl …/'1.0'/data
-    post: sed 's/$version/replaced/g' # expands to: sed 's/'\''1.0'\''/replaced/g'
+    on:
+      write: sed 's/$version/replaced/g' # expands to: sed 's/'\''1.0'\''/replaced/g'
 ```
 
-**Escaping a literal `$`** — use `$$` to emit a literal `$` that is not treated as a variable reference. This is useful in `exec:` and `post:` scripts that contain shell or PowerShell syntax with `$`-prefixed identifiers (e.g. PowerShell built-ins like `$$true` or `$$null`):
+**Escaping a literal `$`** — use `$$` to emit a literal `$` that is not treated as a variable reference. This is useful in `exec:` commands and `on.write` hook scripts that contain shell or PowerShell syntax with `$`-prefixed identifiers (e.g. PowerShell built-ins like `$$true` or `$$null`):
 
 ```yaml
 files:
@@ -1199,7 +1554,8 @@ files:
     src:
       # On Windows exec: runs in PowerShell — $true is a PS built-in, needs $$
       exec: "if ($$true) { Write-Output 'yes' }"
-    post: sed 's/$$HOME/redacted/g' # $HOME would be treated as an avanti variable
+    on:
+      write: sed 's/$$HOME/redacted/g' # $HOME would be treated as an avanti variable
 ```
 
 `$$` produces a single `$` after substitution. `$$$name` produces `$` followed by the value of `name`. `$${expr}` produces a literal `${expr}` — use this to include shell-style `${VAR}` or template placeholders verbatim in a string without avanti interpreting them.
@@ -1326,11 +1682,25 @@ variables:
   registry_line: //$host/:_authToken=$token # both $host and $token are available
 ```
 
-`$latest` is a reserved keyword that resolves to the latest published version and cannot be used as a variable name. For GitLab it resolves to the latest tag sorted by semantic version (for `file:` sources) or the latest release (for `release:` sources, falling back to tags on older instances). For GitHub it resolves to the tag of the latest release (for both `file:` and `release:` sources); if the repository has no releases, it falls back to the most recently created tag. For Bitbucket it resolves to the latest tag sorted by name; if no tags exist, it falls back to the repository's default branch.
+The `ref` (and `release`) field accepts four forms:
+
+- **Literal** — a branch name, tag, or commit hash passed directly to the VCS (e.g. `main`, `v1.2.3`, `abc123`).
+- **`$latest`** — resolves to the newest **stable semver tag** (`vX.Y.Z` or `X.Y.Z`, no pre-release suffix), consistently across all providers. GitHub first checks the published "latest release" and accepts it when it is semver; all providers scan tags filtered by the semver pattern.
+- **`$recent`** — resolves to the most **recently created or published tag**, regardless of its name format. Use this when you want whatever was tagged last, even if it is a nightly or pre-release build. For `git:` remotes the ordering is determined by `git ls-remote` output rather than creation date (date-based ordering requires fetching tag objects and is not supported).
+- **`/pattern/[flags]`** — a regex pattern of the form `/body/` or `/body/flags` (e.g. `ref: /^v1\.\d+\.\d+$/`). Resolves to the first tag whose name matches the pattern, ordered newest-first on GitHub, GitLab, and Bitbucket. For `git:` remotes the match order follows `git ls-remote` output. Flags such as `i` are supported. Note: the pattern body must be non-empty — `//` is treated as a literal ref, not a match-all regex. The stateful flags `g` and `y` are silently stripped; any other unrecognised flag produces an error.
+
+| Form           | Meaning                                          |
+| -------------- | ------------------------------------------------ |
+| `ref: $latest` | Newest `vX.Y.Z` / `X.Y.Z` stable tag             |
+| `ref: $recent` | Most recently created/published tag (any format) |
+| `ref: /^v1\./` | Latest tag matching the regex                    |
+| `ref: main`    | Literal branch / tag / commit                    |
+
+`$latest`, `$recent`, and `$self` are reserved and cannot be used as variable names.
 
 When `ref` is omitted, all source types (GitHub, GitLab, Bitbucket, git) resolve to the repository's default branch.
 
-`$self` is a reserved keyword that expands to the absolute path of the active config file. It is injected automatically and cannot be used as a variable name. Use it anywhere a variable is valid — `exec:` commands, `replace:` rules, `exists:` conditions, `post:` scripts, or any source field:
+`$self` is a reserved keyword that expands to the absolute path of the active config file. It is injected automatically and cannot be used as a variable name. Use it anywhere a variable is valid — `exec:` commands, `replace:` rules, `exists:` conditions, `on.write` scripts, or any source field:
 
 ```yaml
 files:
@@ -1358,7 +1728,9 @@ When the config is specified as a remote spec (e.g. `--config github:org/repo:.a
 
 In addition to `$self` and `$latest`, avanti injects several variables automatically at the start of every run. These names are reserved and cannot be used in `variables:`.
 
-**Per-file path variables** — avanti derives the following variables from each file entry's resolved target path. They can be used in source URLs, `ref:`, conditions, `replace:`, `post:`, template rendering, and `backup:` patterns.
+**Per-file path variables**, **pull-time variables**, and **system variables** are all available everywhere variables are resolved: source URLs, `ref:`, conditions, `replace:`, `on.write` scripts, template rendering, and `backup:` patterns. Side-effect hooks (`on.beforeWrite`, `on.beforeCreate`, `on.beforeUpdate`, `on.create`, `on.update`) do not resolve avanti variables — use `$AVANTI_TARGET` and `$AVANTI_IS_NEW` env vars instead.
+
+**Per-file path variables** — avanti derives the following variables from each file entry's resolved target path.
 
 Example with working directory `/home/user/project` and map key `configs/app.yaml`:
 
@@ -1371,7 +1743,7 @@ Example with working directory `/home/user/project` and map key `configs/app.yam
 | `$dirname`  | `/home/user/project/configs`          |
 | `$basedir`  | `configs`                             |
 
-> **Availability in source URLs and conditions:** per-file path variables are only resolved before the fetch when the map key is a fixed (non-directory) path. They are always available in processors (`replace:`, `post:`, template rendering) and `backup:`.
+> **Availability in source URLs and conditions:** per-file path variables are only resolved before the fetch when the map key is a fixed (non-directory) path. They are always available in processors (`replace:`, `on.write` scripts, template rendering) and `backup:`. Side-effect hooks (`on.create`, `on.update`, etc.) do not resolve avanti variables.
 
 ```yaml
 variables:
@@ -1393,13 +1765,14 @@ files:
     if:
       exists: $path
 
-  # $dirname in a processor — log which directory was updated
+  # $dirname in on.write — transform content using the file's directory name
   app/config.yaml:
     src: github:org/repo/app/config.yaml
-    post: echo updated $dirname >> pull.log
+    on:
+      write: sed "s|__DIR__|$dirname|g"
 ```
 
-**Pull-time variables** — injected once at the start of every run and available everywhere (source URLs, conditions, `replace:`, `post:`, template rendering, `backup:`):
+**Pull-time variables** — injected once at the start of every run and available everywhere (source URLs, conditions, `replace:`, `on.write` scripts, template rendering, `backup:`):
 
 | Variable    | Value                                   | Example               |
 | ----------- | --------------------------------------- | --------------------- |
@@ -1420,6 +1793,34 @@ files:
         to: $datetime
 ```
 
+**System variables** — injected once per run and reflect the machine running avanti. Useful for downloading the correct release artifact for the current OS and CPU architecture:
+
+| Variable | `linux` | `darwin` | `win32`   |
+| -------- | ------- | -------- | --------- |
+| `$os`    | `linux` | `darwin` | `windows` |
+
+| Variable   | `x64`    | `arm64` | `ia32` | `arm` |
+| ---------- | -------- | ------- | ------ | ----- |
+| `$arch`    | `x86_64` | `arm64` | `i686` | `arm` |
+| `$arch_go` | `amd64`  | `arm64` | `386`  | `arm` |
+
+`$arch` uses GNU-triple / Rust naming (`x86_64`). `$arch_go` uses Go / Docker / Kubernetes naming (`amd64`). The `arm64` value is identical in both. Unknown `process.platform` or `process.arch` values are passed through unchanged.
+
+```yaml
+variables:
+  rg_version: '14.1.1'
+  kubectl_version: '1.32.0'
+
+files:
+  # Download the ripgrep tarball for the current system (Rust/GNU naming)
+  releases/ripgrep.tar.gz:
+    src: https://github.com/BurntSushi/ripgrep/releases/download/$rg_version/ripgrep-$rg_version-$arch-unknown-$os.tar.gz
+
+  # Download kubectl for the current system (Go naming)
+  bin/kubectl:
+    src: https://dl.k8s.io/release/v$kubectl_version/bin/$os/$arch_go/kubectl
+```
+
 ### $self — Self-managing Config
 
 The special `$self` key in the `files:` map tells avanti to manage its own config file. When `$self` is present, avanti fetches the listed sources and uses the result as the active config for the rest of the run — all in a single invocation.
@@ -1462,7 +1863,7 @@ files:
       arrays: concat
 ```
 
-`$self` supports all the same source types, `replace`, `post`, and YAML/JSON merge options as any other file entry. See [Self-managing Config](#self-managing-config) in the Use Cases section for a full worked example.
+`$self` supports all the same source types, `replace`, `on.write`, and YAML/JSON merge options as any other file entry. Lifecycle hooks (`on.beforeWrite`, `on.beforeCreate`, `on.beforeUpdate`, `on.create`, `on.update`) are not supported for `$self` — they require a confirmed write context that the config re-evaluation pass does not have. See [Self-managing Config](#self-managing-config) in the Use Cases section for a full worked example.
 
 ### Authentication