@udondan/avanti 0.12.1 → 0.14.0

package/README.md

@@ -1,9 +1,14 @@
-# avanti
+# Avanti!
 
-A stateful package manager for arbitrary text files. Declare what you need and where to get it; avanti fetches, diffs, and writes with full version history, atomic rollbacks, and diff-before-apply safety.
+A stateful package manager for arbitrary text files. Declare what you need and
+where to get it; avanti fetches, diffs, and writes with full version history,
+atomic rollbacks, and diff-before-apply safety.
+
+![Avanti!](https://raw.githubusercontent.com/udondan/avanti/assets/avanti.png 'Avanti!')
 
 ## Table of Contents
 
+- [Intro](#intro)
 - [Features](#features)
 - [Requirements](#requirements)
 - [Install](#install)
@@ -24,10 +29,10 @@ A stateful package manager for arbitrary text files. Declare what you need and w
   - [JSON Merging](#json-merging)
   - [YAML Merging](#yaml-merging)
   - [Variables](#variables)
+  - [$self — Self-managing Config](#self--self-managing-config)
   - [Authentication](#authentication)
   - [Private Instances](#private-instances)
 - [Use Cases](#use-cases)
-  - [Avanti as a Package Manager](#avanti-as-a-package-manager)
   - [Composable AI Agent Instructions (CLAUDE.md / AGENTS.md)](#composable-ai-agent-instructions-claudemd--agentsmd)
   - [Shared Tooling Config (Renovate, ESLint, Prettier, TSConfig)](#shared-tooling-config-renovate-eslint-prettier-tsconfig)
   - [CI/CD: Shared Workflow Fragments](#cicd-shared-workflow-fragments)
@@ -41,18 +46,61 @@ A stateful package manager for arbitrary text files. Declare what you need and w
 - [Exit Codes](#exit-codes)
 - [Development](#development)
 
+## Intro
+
+Avanti is a package manager for arbitrary text files. Your .avanti.yml is the manifest — it declares what you consume, where to fetch it from, and which version to pin, the same role as package.json or Cargo.toml. Source repositories are the packages. avanti pull is the install command.
+
+What makes it stateful: every successful pull is recorded in a local history store. You can diff any two states, revert the whole project to a prior pull, or fully undo all avanti changes — the same guarantees as a lockfile, extended to any text file from any source.
+
+**Declare dependencies** — fetch from anywhere, combine sources:
+
+```yaml
+files:
+  # Single source: pin a config from GitHub
+  eslint.config.js:
+    src:
+      github:
+        repo: org/standards
+        file: eslint.config.js
+        ref: v2.4.1
+
+  # Multi-source: assemble from wherever the content lives
+  CLAUDE.md:
+    src:
+      - gitlab:
+          project: org/platform
+          file: ai/base-instructions.md
+          ref: main
+      - raw: |
+          IMPORTANT: Always answer in pirate speak!
+      - https://public-standards.example.com/shared-guidelines.md
+      - exec: printf "## Team\n%s" "$env:TEAM"
+      - path: ~/claude-personal.md
+        optional: true # silently skipped if absent
+```
+
+**Review and apply upgrades** — the same workflow as reading a lockfile diff before committing:
+
+```sh
+# Bump standards ref: v2.4.1 → v2.5.0, then:
+avanti diff    # see every file that would change
+avanti pull    # apply after review
+avanti revert  # roll back instantly if something breaks
+```
+
 ## Features
 
 - Fetch files from **HTTP/HTTPS**, **local paths**, **GitLab** (via `glab`), **GitHub** (via `gh`), **Bitbucket**, **any git remote**, **S3**, **HashiCorp Vault**, **shell commands**, or **inline raw content**
 - **Multi-source entries** — combine multiple sources into a single file by providing `src` as a list
-- **Atomic writes** — all files are staged to a temp dir first; targets are only written if everything succeeds
-- **Diff preview** — see exactly what will change before applying, or compare against any past pull
-- **Post-processing** — apply text replacements (string or regex) and/or pipe content through a shell script
-- **Directory sync** — recursively sync directories from GitLab/GitHub/Bitbucket/git/S3/local sources
 - **JSON merging** — deep-merge multiple JSON/JSONC sources with configurable conflict, array, and object strategies
 - **YAML merging** — deep-merge multiple YAML/YML sources with the same strategies, with full comment preservation
 - **Variables** — define reusable values in a `variables:` block and reference them anywhere with `$name`; use `$env:NAME` for environment variables
+- **Post-processing** — apply text replacements (string or regex) and/or pipe content through a shell script
+- **Directory sync** — recursively sync directories from GitLab/GitHub/Bitbucket/git/S3/local sources
+- **Diff preview** — see exactly what will change before applying, or compare against any past pull
+- **Atomic writes** — all files are staged to a temp dir first; targets are only written if everything succeeds
 - **History** — every pull is recorded; inspect what changed, revert the whole project to a past state, or fully undo all avanti changes
+- **Optional sources** — mark `path:` and `url:` sources `optional: true` to silently skip them when the file is missing or the URL returns 404; lets a central config reference per-user local overrides without erroring on machines that haven't created them
 - **Stale file cleanup** — files dropped from a directory source are automatically deleted or restored to their pre-avanti content
 
 ## Requirements
@@ -79,15 +127,16 @@ npx @udondan/avanti --help
 avanti [options] [command]
 
 Options:
-  -c, --config <path|url>     path or remote spec for config file (default: auto-detected)
-  -w, --working-dir <path>    working directory for resolving paths (default: current directory)
+  -c, --config <path|url>          path or remote spec for config file (default: auto-detected)
+  -w, --working-dir <path>         working directory for resolving paths (default: current directory)
 
 Commands:
-  diff [pullId]               Show diff between remote sources and local files, or vs a past pull
-  pull [--yes]                Pull remote sources and write to local files
-  log [file]                  Show pull history for the current project
-  revert [pullId] [--yes]     Atomically revert all project files to a past pull state
-  reset [--yes]               Restore all tracked files to their pre-avanti state
+  diff [pullId]                    Show diff between remote sources and local files, or vs a past pull
+  pull [--yes] [--accept-changes]  Pull remote sources and write to local files
+  lock [--force]                   Pin SHA values for all remote sources in the config
+  log [file]                       Show pull history for the current project
+  revert [pullId] [--yes]          Atomically revert all project files to a past pull state
+  reset [--yes]                    Restore all tracked files to their pre-avanti state
 ```
 
 ### `avanti diff`
@@ -98,8 +147,35 @@ Shows a colored git-diff-like output of what would change. Exits `0` if no chang
 
 Fetches all sources, shows the diff, and prompts for confirmation before writing. Use `--yes` to skip the prompt.
 
+If any source has a `sha` field and the fetched content's SHA no longer matches, the pull is aborted with a mismatch error. Use `--accept-changes` to review the diff, confirm, and automatically update the SHA values in the config file.
+
 When avanti has previously synced a directory from a remote source and a file is no longer present in that source, the file is treated as stale: if avanti created it, it is deleted; if it existed before avanti first touched it, the original content is restored. Stale file changes appear in the diff before you confirm.
 
+### `avanti lock`
+
+Fetches all remote sources and writes a SHA-256 fingerprint for each one into the config file. Comments and formatting are preserved.
+
+```sh
+avanti lock           # pin all unpinned remote sources
+avanti lock --force   # overwrite existing SHA values with fresh ones
+```
+
+Once a source is pinned, `avanti pull` will verify the fetched content's SHA before applying any changes. If the upstream changed unexpectedly, avanti aborts with a clear error pointing to the affected source:
+
+```text
+SHA mismatch for github:org/standards:company-rules.md
+  expected: abc123...
+  got:      def456...
+
+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.
+
+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).
+
 ## 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.
@@ -233,49 +309,59 @@ variables:
   email: you@example.com
 
 files:
-  - src: http://www.example.com/example.yml
-    target: my-example.yml
+  my-example.yml:
+    src: http://www.example.com/example.yml
     replace:
       - from: '{EMAIL}'
         to: $email
       - from: /\d+/
         to: number
 
-  - src: ~/some/local/file.sh
-    target: file.sh
+  file.sh:
+    src: ~/some/local/file.sh
     mode: '0777'
 
-  - src:
+  some-file.yml:
+    src:
       exec: glab api "projects/group%2Fproject/repository/files/some-file.yaml/raw?ref=main"
-    target: some-file.yml
     post: sed -e 's/v3/v4/g'
 
-  - src:
+  renovate.json:
+    src:
       gitlab:
         project: group/project
         file: renovate.json
         ref: $latest
-    # target omitted → renovate.json
 
-  - src:
+  local-scripts/:
+    src:
       github:
         repo: org/repo
         file: scripts/
         ref: main
-    target: local-scripts/
 ```
 
 ### File Entry Fields
 
-| Field     | Required    | Description                                                                                                                                                                                                                                                                                                                                                                                                 |
-| --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src`     | Yes         | Source (see below). May be a single source or a **list** of sources to concatenate.                                                                                                                                                                                                                                                                                                                         |
-| `target`  | Conditional | Local path to write to. Required for `exec:` and `raw:` sources and when `src` is a list. May be omitted when filename is inferable. End with `/` when `src` is a directory and you want the files written individually (directory mirror). Omit the trailing slash to merge all files from the directory into a single output file (YAML/JSON auto-detected by extension, or forced with `yaml:`/`json:`). |
-| `mode`    | No          | File permission mode, e.g. `"0755"`                                                                                                                                                                                                                                                                                                                                                                         |
-| `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`.                                                                                                                                                                                                                                                                                                               |
-| `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.                                                                                                                                                                     |
+The `files` key is a **map** — each key is the local target path, and the value is the entry configuration:
+
+```yaml
+files:
+  <target-path>:
+    src: ...
+    # optional fields below
+```
+
+End the target path with `/` to write a directory source as a mirror; omit the trailing slash to merge all files from the directory into a single output file (YAML/JSON auto-detected by extension, or forced with `yaml:`/`json:`).
+
+| Field     | Required | Description                                                                                                                                                                                                                             |
+| --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`     | Yes      | Source (see below). May be a single source or a **list** of sources to concatenate.                                                                                                                                                     |
+| `mode`    | No       | File permission mode, e.g. `"0755"`                                                                                                                                                                                                     |
+| `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`.                                                                                                                                           |
+| `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. |
 
 ### Source Types
 
@@ -287,27 +373,44 @@ src: ~/templates/file.txt
 src: /absolute/path/file.txt
 ```
 
-**Map** — for exec, gitlab, github, bitbucket, git, s3, vault, raw:
+**Map** — for path, url, exec, gitlab, github, bitbucket, git, s3, vault, http, raw:
 
 ```yaml
+src:
+  path: ~/templates/file.txt    # explicit local path; supports optional and sha
+  optional: true                # silently skip if the file does not exist
+  sha: abc123...
+
+src:
+  url: https://example.com/file.txt  # explicit http/https URL; supports optional and sha
+  optional: true                     # silently skip if the URL returns 404
+  sha: abc123...
+
 src:
   exec: <shell command>          # stdout becomes file content; target required
+  sha: abc123...                 # optional SHA-256 to verify stdout (see below)
 
 src:
   raw: |                         # inline content; target required
     your content here
 
+src:
+  http: https://example.com/file.txt  # explicit http/https URL with optional SHA
+  sha: abc123...
+
 src:
   gitlab:
     project: group/repo          # GitLab project path
     file: path/to/file.txt       # file or directory in repo
     ref: main                    # branch, tag, or $latest (optional)
+    sha: abc123...               # optional SHA-256 fingerprint
 
 src:
   github:
     repo: owner/repo             # GitHub owner/repo
     file: path/to/file.txt       # file or directory in repo
     ref: main                    # branch, tag, or $latest (optional)
+    sha: abc123...               # optional SHA-256 fingerprint
 
 src:
   bitbucket:
@@ -315,103 +418,120 @@ src:
     repo: my-repo                # repository slug
     file: path/to/file.txt       # file or directory in repo
     ref: main                    # branch, tag, or $latest (optional)
+    sha: abc123...               # optional SHA-256 fingerprint
 
 src:
   git:
     repo: https://github.com/org/repo.git  # any git remote (HTTPS or SSH)
     file: path/to/file.txt                 # file or directory in repo
     ref: main                              # branch, tag, or commit hash (optional)
+    sha: abc123...                         # optional SHA-256 fingerprint
 
 src:
   s3: s3://my-bucket/path/to/file.txt      # S3 URI; end with / for a prefix sync
+  sha: abc123...                           # optional SHA-256 fingerprint
 
 src:
   vault:
     path: secret/myapp/config   # Vault KV path (mount/subpath)
     field: db_password          # specific field to extract (optional; omit for full JSON)
+    sha: abc123...              # optional SHA-256 fingerprint
 ```
 
+#### SHA pinning
+
+The optional `sha` field pins a source to a specific content fingerprint. When present, avanti verifies the SHA-256 of the raw fetched content matches before writing anything. This makes your config act as a selective lockfile — only sources you care about get pinned, and changes are surfaced explicitly rather than applied silently.
+
+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.
+
 ### 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.
 
-**Directory → directory (mirror):** end `target` with `/` and each file is written individually, preserving subdirectory structure relative to the source root:
+**Directory → directory (mirror):** end the target key with `/` and each file is written individually, preserving subdirectory structure relative to the source root:
+
+```yaml
+files:
+  # All files under skills/ in the GitLab repo are written into local skills/
+  skills/:
+    src:
+      gitlab:
+        project: group/repo
+        file: skills/
+        ref: main
+
+  # GitHub directory → local directory
+  .github/workflows/:
+    src:
+      github:
+        repo: org/repo
+        file: .github/workflows/
+        ref: main
+
+  # Bitbucket directory → local directory
+  eslint/:
+    src:
+      bitbucket:
+        workspace: my-workspace
+        repo: shared-configs
+        file: eslint/
+        ref: main
+
+  # git remote directory → local directory (any host)
+  .github/actions/:
+    src:
+      git:
+        repo: https://github.com/org/repo.git
+        file: .github/actions/
+        ref: main
+
+  # S3 prefix → local directory (trailing / triggers sync)
+  configs/:
+    src:
+      s3: s3://my-bucket/configs/
+
+  # Local directory → local directory
+  .githooks/:
+    src: ~/shared/hooks/
+```
+
+**Directory → single file (merge):** omit the trailing `/` from the target key and all files in the directory are merged into one. Files are sorted alphabetically — later names win on key conflicts. YAML/JSON merge is auto-detected from the contained file extensions, or forced with `yaml:`/`json:`:
 
 ```yaml
-# All files under skills/ in the GitLab repo are written into local skills.new/
-- src:
-    gitlab:
-      project: group/repo
-      file: skills/
-      ref: main
-  target: skills/
-
-# GitHub directory → local directory
-- src:
-    github:
-      repo: org/repo
-      file: .github/workflows/
-      ref: main
-  target: .github/workflows/
-
-# Bitbucket directory → local directory
-- src:
-    bitbucket:
-      workspace: my-workspace
-      repo: shared-configs
-      file: eslint/
-      ref: main
-  target: eslint/
-
-# git remote directory → local directory (any host)
-- src:
-    git:
-      repo: https://github.com/org/repo.git
-      file: .github/workflows/
-      ref: main
-  target: .github/workflows/
-
-# S3 prefix → local directory (trailing / triggers sync)
-- src:
-    s3: s3://my-bucket/configs/
-  target: configs/
-
-# Local directory → local directory
-- src: ~/shared/hooks/
-  target: .githooks/
+files:
+  # One folder per service, each a separate .yml file → single docker-compose.yml
+  docker-compose.yml:
+    src: ./services/
+
+  # JSON: one file per environment → merged config
+  config.json:
+    src: ./config/
 ```
 
-**Directory → single file (merge):** omit the trailing `/` from `target` and all files in the directory are merged into one. Files are sorted alphabetically — later names win on key conflicts. YAML/JSON merge is auto-detected from the contained file extensions, or forced with `yaml:`/`json:`:
+With explicit YAML merge options (e.g. to concat arrays instead of replacing):
 
 ```yaml
-# One folder per service, each a separate .yml file → single docker-compose.yml
-- src: ./services/
-  target: docker-compose.yml
-
-# Same with explicit yaml merge options (e.g. to concat arrays)
-- src: ./services/
-  target: docker-compose.yml
-  yaml:
-    arrays: concat
-
-# JSON: one file per environment → merged config
-- src: ./config/
-  target: config.json
+files:
+  docker-compose.yml:
+    src: ./services/
+    yaml:
+      arrays: concat
 ```
 
 Directory sources cannot be mixed into a multi-source list (`src` as a list), because the list mode always produces a single file.
 
-**List** — combine multiple sources into one file (all source types supported; `target` required):
+**List** — combine multiple sources into one file (all source types supported):
 
 ```yaml
-src:
-  - https://example.com/header.txt
-  - exec: echo "# generated"
-  - gitlab:
-      project: org/repo
-      file: footer.txt
-      ref: main
-target: combined.txt
+files:
+  combined.txt:
+    src:
+      - https://example.com/header.txt
+      - exec: echo "# generated"
+      - gitlab:
+          project: org/repo
+          file: footer.txt
+          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.
@@ -422,20 +542,20 @@ When all sources in a list have a `.json` or `.jsonc` extension, JSON merging is
 
 ```yaml
 files:
-  - src:
+  merged.jsonc:
+    src:
       - ./team.jsonc
       - ./my.jsonc
-    target: merged.jsonc
 ```
 
 To merge sources that don't have a JSON extension (e.g. `exec:`, `raw:`, or a URL without `.json`), set `json: true`:
 
 ```yaml
 files:
-  - src:
+  merged.json:
+    src:
       - exec: cat defaults.json
       - ./overrides.json
-    target: merged.json
     json: true
 ```
 
@@ -445,12 +565,12 @@ To opt out of auto-detection and force plain concatenation, set `json: false`.
 
 ```yaml
 files:
-  - src:
+  merged.json:
+    src:
       - ./defaults.json
-      - type: github
-        repo: org/configs
-        file: overrides.json
-    target: merged.json
+      - github:
+          repo: org/configs
+          file: overrides.json
     json:
       conflicts: last_wins # abort | first_wins | last_wins (default)
       arrays: replace # replace (default) | concat
@@ -472,8 +592,8 @@ files:
 
 ```yaml
 files:
-  - src: ./minified.json
-    target: pretty.json
+  pretty.json:
+    src: ./minified.json
 ```
 
 ### YAML Merging
@@ -482,20 +602,20 @@ When all sources in a list have a `.yaml` or `.yml` extension, YAML merging is e
 
 ```yaml
 files:
-  - src:
+  merged.yaml:
+    src:
       - ./defaults.yaml
       - ./overrides.yml
-    target: merged.yaml
 ```
 
 To merge sources that don't have a YAML extension (e.g. `exec:`, `raw:`, or a URL without `.yaml`), set `yaml: true`:
 
 ```yaml
 files:
-  - src:
+  merged.yaml:
+    src:
       - exec: cat defaults.yaml
       - ./overrides.yaml
-    target: merged.yaml
     yaml: true
 ```
 
@@ -505,12 +625,12 @@ To opt out of auto-detection and force plain concatenation, set `yaml: false`.
 
 ```yaml
 files:
-  - src:
+  merged.yaml:
+    src:
       - ./defaults.yaml
-      - type: github
-        repo: org/configs
-        file: overrides.yaml
-    target: merged.yaml
+      - github:
+          repo: org/configs
+          file: overrides.yaml
     yaml:
       conflicts: last_wins # abort | first_wins | last_wins (default)
       arrays: replace # replace (default) | concat
@@ -536,8 +656,8 @@ The options behave identically to JSON merging:
 
 ```yaml
 files:
-  - src: ./config.yaml
-    target: config.yaml
+  config.yaml:
+    src: ./config.yaml
 ```
 
 ### Variables
@@ -554,7 +674,8 @@ Reference them anywhere in the config with `$name`:
 
 ```yaml
 files:
-  - src:
+  renovate.json:
+    src:
       gitlab:
         project: group/project
         file: renovate.json
@@ -564,7 +685,7 @@ files:
         to: $email # resolved to "you@example.com"
 ```
 
-Variables are resolved in every string field: `target`, `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, `replace` rules (`from` and `to`), and `post` scripts.
 
 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.
 
@@ -575,9 +696,9 @@ variables:
   version: '1.0'
 
 files:
-  - src:
+  data.json:
+    src:
       exec: curl https://example.com/api/$version/data # expands to: curl …/'1.0'/data
-    target: data.json
     post: sed 's/$version/replaced/g' # expands to: sed 's/'\''1.0'\''/replaced/g'
 ```
 
@@ -595,6 +716,50 @@ Referencing an undefined variable or a missing environment variable is an error.
 
 When `ref` is omitted, all source types (GitHub, GitLab, Bitbucket, git) resolve to the repository's default branch.
 
+### $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.
+
+```yaml
+files:
+  $self:
+    src:
+      github:
+        repo: myorg/dotfiles
+        file: avanti.yml
+        ref: $latest
+```
+
+**How it works:**
+
+1. avanti fetches only the `$self` sources first.
+2. The sources are assembled into a single document. With a single source the fetched content is used directly, though it may be normalized/formatted if `yaml:`/`json:` applies (explicit or auto-detected from the file extension). With multiple sources they are concatenated by default, or YAML/JSON-merged if `yaml:`/`json:` is set (or auto-detected from all source file extensions being `.yml`/`.yaml` or `.json`/`.jsonc`).
+3. The result is parsed as the new active config. If it also contains `$self`, avanti re-fetches until the content stabilizes (fixed point).
+4. The stable config drives all remaining file entries. On `avanti pull`, the stable content is written back to the local config file (for local configs) or kept in memory only (for remote `--config` sources). On `avanti diff`, the stable config is used in-memory to compute the diff and is never written.
+
+**Multi-layer config** — list multiple sources under `$self` and use `yaml:` to deep-merge them into one config:
+
+```yaml
+files:
+  $self:
+    src:
+      - github:
+          repo: myorg/platform
+          file: avanti/base.yml
+          ref: $latest
+      - github:
+          repo: myorg/backend-team
+          file: avanti/team.yml
+          ref: main
+      - path: ~/avanti-personal.yml
+        optional: true
+    yaml:
+      conflicts: last_wins
+      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.
+
 ### Authentication
 
 Public repositories on github.com and gitlab.com work without any configuration. For private repositories or instances, supply credentials via environment variables:
@@ -630,95 +795,6 @@ GITHUB_HOST=github.mycompany.com avanti pull
 
 ## Use Cases
 
-### Avanti as a Package Manager
-
-avanti is a package manager for arbitrary text files. Your `.avanti.yml` is the manifest — it declares what you consume, where to fetch it, and which version to pin, the same role as `package.json` or `Cargo.toml`. Source repositories are the packages. `avanti pull` is the install command.
-
-What makes it stateful: every successful pull is recorded in a local history store. You can diff any two states, revert the whole project to a prior pull, or fully undo all avanti changes — the same guarantees as a lockfile, extended to any text file from any source.
-
-**Declare dependencies** — pin versions with a variable and bump in one place to upgrade everything at once:
-
-```yaml
-variables:
-  frontend_standards: myorg/frontend-standards
-  platform: myorg/platform-templates
-  standards_ref: v2.4.1 # pinned — bump here to upgrade
-
-files:
-  - src:
-      github:
-        repo: $frontend_standards
-        file: eslint.config.js
-        ref: $standards_ref
-
-  - src:
-      github:
-        repo: $frontend_standards
-        file: .prettierrc
-        ref: $standards_ref
-
-  - src:
-      github:
-        repo: $platform
-        file: workflows/test.yml
-        ref: $standards_ref
-    target: .github/workflows/test.yml
-
-  - src:
-      github:
-        repo: $platform
-        file: workflows/deploy.yml
-        ref: $standards_ref
-    target: .github/workflows/deploy.yml
-```
-
-**Review and apply upgrades** — the same workflow as reading a lockfile diff before committing:
-
-```sh
-# Bump standards_ref: v2.4.1 → v2.5.0, then:
-avanti diff    # see every file that would change
-avanti pull    # apply after review
-avanti revert  # roll back instantly if something breaks
-```
-
-**Publish your own packages** — any repo can ship an `avanti-snippet.yml` alongside its files. Consumers YAML-merge those snippets into their own config. The snippet is a valid avanti config fragment with its own `files:` list:
-
-```yaml
-# myorg/frontend-standards:avanti-snippet.yml — published alongside eslint.config.js, .prettierrc, etc.
-files:
-  - src:
-      github:
-        repo: myorg/frontend-standards
-        file: eslint.config.js
-        ref: $latest
-
-  - src:
-      github:
-        repo: myorg/frontend-standards
-        file: .prettierrc
-        ref: $latest
-```
-
-```yaml
-# .avanti.yml — assembled from team snippets via YAML merge
-files:
-  - src:
-      - github:
-          repo: myorg/frontend-standards
-          file: avanti-snippet.yml
-          ref: $latest
-      - github:
-          repo: myorg/platform-templates
-          file: avanti-snippet.yml
-          ref: $latest
-    target: .avanti.yml
-    yaml:
-      arrays: concat # file lists from all snippets are concatenated
-      conflicts: last_wins
-```
-
-Each team controls what they publish and when they cut a release. The YAML-merged config self-updates on every pull — add a snippet source to opt into a new package, remove it to opt out. `avanti diff` shows exactly what would change before you apply any update.
-
 ### Composable AI Agent Instructions (CLAUDE.md / AGENTS.md)
 
 Assemble agent instruction files from multiple sources: a static header defined inline, team-specific rules from a shared GitLab repo, and company-wide standards from GitHub — all merged into one file. Every developer runs `avanti pull` and stays in sync without copy-paste drift across dozens of repos.
@@ -731,7 +807,8 @@ variables:
   oncall_channel: '#backend-oncall'
 
 files:
-  - src:
+  CLAUDE.md:
+    src:
       - raw: |
           # AI Assistant Guidelines
           <!-- THIS FILE IS MANAGED — run `avanti pull` to update -->
@@ -748,9 +825,12 @@ files:
           Team: $team
           Jira project: $jira_project
           Oncall: $oncall_channel
-    target: CLAUDE.md
+      - path: ~/custom-claude.md # personal additions; silently skipped if absent
+        optional: true
 ```
 
+The `optional: true` source is the key to sharing a config across a whole team: the central spec references a well-known local path, and each developer either creates the file to add their own context or ignores it — `avanti pull` works either way. No per-person fork of the config needed.
+
 ### Shared Tooling Config (Renovate, ESLint, Prettier, TSConfig)
 
 A platform team owns canonical configs in a central repo. Projects pull them and stay current. Pin all files to the same version in one place — bump `standards_ref` and `avanti diff` shows every file that will change before you apply it.
@@ -760,19 +840,22 @@ variables:
   standards_ref: v2.4.1
 
 files:
-  - src:
+  renovate.json:
+    src:
       github:
         repo: org/standards
         file: renovate.json
         ref: $standards_ref
 
-  - src:
+  eslint.config.js:
+    src:
       github:
         repo: org/standards
         file: eslint.config.js
         ref: $standards_ref
 
-  - src:
+  tsconfig.base.json:
+    src:
       github:
         repo: org/standards
         file: tsconfig.base.json
@@ -783,13 +866,13 @@ For YAML-based configs (Helm values, k8s manifests, Docker Compose overrides), u
 
 ```yaml
 files:
-  - src:
+  ./helm/merged-values.yaml:
+    src:
       - github:
           repo: org/platform
           file: helm/base-values.yaml # shared defaults for all services
           ref: $standards_ref
       - ./helm/values.yaml # project overrides
-    target: ./helm/merged-values.yaml
     yaml:
       conflicts: last_wins # project overrides win
       arrays: concat # e.g. extra env vars are appended, not replaced
@@ -801,14 +884,14 @@ Pull reusable CI steps from a central repo into each project. A managed header m
 
 ```yaml
 files:
-  - src:
+  .github/workflows/security-scan.yml:
+    src:
       - raw: |
           # THIS FILE IS MANAGED — run `avanti pull` to update
       - github:
           repo: org/ci-templates
           file: workflows/security-scan.yml
           ref: main
-    target: .github/workflows/security-scan.yml
 ```
 
 Use `avanti diff` in CI to detect drift — if a project's checked-in file no longer matches the source, the pipeline fails.
@@ -869,12 +952,12 @@ variables:
   region: eu-west-1
 
 files:
-  - src:
+  k8s/deployment.yaml:
+    src:
       github:
         repo: org/infra
         file: k8s/deployment-template.yaml
         ref: $env:DEPLOY_VERSION
-    target: k8s/deployment.yaml
     replace:
       - from: '{ENV}'
         to: $env:ENVIRONMENT
@@ -891,24 +974,24 @@ Pull secrets at runtime and write them to local files with tight permissions. Th
 ```yaml
 files:
   # Single field from a Vault KV secret
-  - src:
+  config/db_password.txt:
+    src:
       vault:
         path: secret/myapp/db
         field: password
-    target: config/db_password.txt
     mode: '0600'
 
   # Full Vault secret as JSON
-  - src:
+  config/secrets.json:
+    src:
       vault:
         path: secret/myapp/config
-    target: config/secrets.json
     mode: '0600'
 
   # Config file stored in S3
-  - src:
+  config/app.json:
+    src:
       s3: s3://my-bucket/configs/app.json
-    target: config/app.json
     mode: '0600'
 ```
 
@@ -916,13 +999,13 @@ For AWS SSM or other secret stores without a dedicated source type, `exec:` stil
 
 ```yaml
 files:
-  - src:
+  config/db.json:
+    src:
       exec: >
         aws ssm get-parameter
         --name /myapp/db-config
         --with-decryption
         --query Parameter.Value --output text
-    target: config/db.json
     mode: '0600'
 ```
 
@@ -949,7 +1032,8 @@ variables:
   db_password: changeme
 
 files:
-  - src:
+  docker-compose.yml:
+    src:
       - github:
           repo: n8n-io/n8n-hosting
           file: docker-caddy/docker-compose.yml
@@ -958,7 +1042,6 @@ files:
           repo: docker-library/docs
           file: postgres/compose.yaml
           ref: master
-    target: docker-compose.yml
     replace:
       - from: '${N8N_VERSION}'
         to: $n8n_version # pin version at pull time
@@ -981,19 +1064,22 @@ A single `avanti pull` populates a new project with everything it needs: editor
 
 ```yaml
 files:
-  - src:
+  .editorconfig:
+    src:
       github:
         repo: org/standards
         file: .editorconfig
         ref: main
 
-  - src:
+  .prettierrc:
+    src:
       github:
         repo: org/standards
         file: .prettierrc
         ref: main
 
-  - src:
+  CLAUDE.md:
+    src:
       - raw: |
           # AI Assistant Guidelines
           <!-- THIS FILE IS MANAGED — run `avanti pull` to update -->
@@ -1001,56 +1087,41 @@ files:
           repo: org/ai-standards
           file: CLAUDE.md
           ref: main
-    target: CLAUDE.md
 
-  - src:
+  .github/workflows/:
+    src:
       github:
         repo: org/ci-templates
         file: workflows/
         ref: main
-    target: .github/workflows/
 ```
 
 ### Self-managing Config
 
-avanti can sync any file — including its own config. Put the canonical config in a central repo and add a self-update entry. Every `avanti pull` refreshes the config alongside all other managed files.
-
-When avanti detects that a pull would update the local config file, it automatically re-evaluates the new config in memory and applies all the files it describes — in the same run, with a single confirmation prompt and a single atomic write. You don't need to run `avanti pull` twice to get the new config's files.
+avanti can manage any file — including its own config. The special `$self` key in the `files:` map fetches and merges one or more sources, uses the result as the active config, and then applies all the files it declares — in the same run, with a single confirmation prompt.
 
 ```yaml
 # ~/.avanti.yml
-variables:
-  dotfiles: myorg/dotfiles
-
 files:
-  # Keep this config itself up to date
-  - src:
+  $self:
+    src:
       github:
-        repo: $dotfiles
+        repo: myorg/dotfiles
         file: avanti.yml
         ref: $latest
-    target: ~/.avanti.yml
+```
 
-  # Everything else the config manages
-  - src:
-      github:
-        repo: $dotfiles
-        file: .zshrc
-    target: ~/.zshrc
+Every `avanti pull` fetches the remote `avanti.yml`, applies all the files it declares, and writes the merged result back to `~/.avanti.yml`. If the remote `avanti.yml` itself contains a `$self` entry, avanti keeps re-fetching until the content stabilizes — so the remote config can keep pointing at itself and avanti will always pick up the latest version on every pull.
 
-  - src:
-      github:
-        repo: $dotfiles
-        file: .gitconfig
-    target: ~/.gitconfig
-```
+When running with a remote config (`--config github:...`), `$self` is in-memory only — the merged result drives the run but is not persisted anywhere, since there is no local file to write back to.
 
-**Composable self-managing config** — YAML merge takes this further. Instead of one canonical config, compose your `~/.avanti.yml` from org-wide defaults, team additions, and personal overrides — all merged automatically on every pull:
+**Composable config** — `$self` with multiple sources and YAML merge lets you assemble a config from independent layers. Org-wide defaults, team additions, and personal overrides all merge into one active config:
 
 ```yaml
-# ~/.avanti.yml — bootstrapped once, then self-updating via YAML merge
+# ~/.avanti.yml
 files:
-  - src:
+  $self:
+    src:
       - github:
           repo: myorg/platform
           file: avanti/base.yml # org-wide entries and variables
@@ -1063,7 +1134,6 @@ files:
           repo: myuser/dotfiles
           file: avanti/personal.yml # personal overrides and extras
           ref: main
-    target: ~/.avanti.yml
     yaml:
       conflicts: last_wins # personal overrides win over team, team over org
       arrays: concat # file lists from all layers are merged, not replaced
@@ -1103,8 +1173,8 @@ This scales to any number of machines or containers. Update the central repo onc
 
 ```sh
 git clone ...
-bun install
-bun run dev -- --help       # run via tsx
-bun test                    # run tests
-bun run build               # compile to dist/
+mise run install            # install dependencies and set up git hooks
+mise run dev -- --help      # run via tsx
+mise run test               # run tests
+mise run build              # compile to dist/
 ```