feat(installer): leave the installed system able to update the tools it was given

Every tool this project ships except the installer now goes into the target, together with the keyring the rest are checked against, and the bootstrap writes this project's repository into the target's own pacman.conf. It is the published address and never the medium's, which is a copy of one moment on a filesystem that will not be there once the machine is running; and it goes above the official ones, where Package Repository has always said it belongs, which means in front of the first repository in the file rather than appended below every one of them. The same correction applies to the medium, where appending had been putting it under core and extra all along.

And an installation no longer fetches what it is standing on. The medium's repository is named as a package cache as well as served as a repository — one directory, so the image does not grow — and a package already there at the version being installed is taken rather than downloaded. What makes that reach pacman is -c, which leaves the cache to the configuration instead of pacstrap's command line, and it is passed only where the medium says where its cache is: the official Arch image says nothing, and there the downloads would land in the live system's own directories, which are memory.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01484ofT7TdcBt7bgNyhUn5D

Author: montyclt

archiso/build.sh

@@ -31,6 +31,30 @@ readonly MEDIUM_REPO_DIR=/usr/share/oparch/repo
 # other, so a run given it synchronises nothing and reaches for nothing.
 readonly MEDIUM_CONF=/usr/share/oparch/medium.conf
 
+# Where an installation keeps what it had to fetch. It is the installer's mount
+# point, which is fixed, and the cache has to be on the target rather than on
+# the medium: the live system's own directories are memory, and a bootstrap is
+# more of it than a small machine has.
+readonly TARGET_CACHE=/mnt/var/cache/pacman/pkg
+
+# Everything from the top of a pacman configuration down to the first
+# repository, which is what `[options]` is; and the repositories after it, in
+# the order pacman reads them. Commented-out repositories are not headers and
+# stay where they were written.
+options_section() { awk '/^\[/ && $0 != "[options]" { exit } { print }' "$1"; }
+repositories_section() {
+    awk 'found { print } !found && /^\[/ && $0 != "[options]" { found = 1; print }' "$1"
+}
+
+# Where the packages an installation installs are looked for before any of them
+# is fetched. The first is on the target, and is where whatever did have to be
+# downloaded is kept. The second is the medium's own repository — the same
+# directory that serves it, so the files are on the image once and named twice
+# — and a package whose exact version is already there is not downloaded again.
+package_cache() {
+    printf 'CacheDir = %s/\nCacheDir = %s/\n' "$TARGET_CACHE" "$MEDIUM_REPO_DIR"
+}
+
 # The stanza that names the repository the medium carries. Both files that
 # mention it are written from here, so they cannot come to disagree about where
 # it is or what is asked of what it holds.
@@ -103,13 +127,19 @@ pacman-key --add "$HERE/../packages/oparch-keyring/oparch.gpg"
 pacman-key --lsign-key "$fingerprint"
 
 # The published repository, above the official ones, so that the medium is
-# built out of the same packages an installed system would update to.
-cat >> "$profile/pacman.conf" <<EOF
-
-[$REPOSITORY_NAME]
-SigLevel = Required TrustedOnly
-Server = $REPOSITORY
-EOF
+# built out of the same packages an installed system would update to, and so
+# that a name this project publishes resolves to this project's package
+# wherever else that name turns up. Above means in front of the first
+# repository in the file and not at the end of it, which is where appending
+# would put it: below every official one.
+say "Adding the published repository, above the official ones"
+{
+    options_section "$profile/pacman.conf"
+    printf '\n[%s]\nSigLevel = Required TrustedOnly\nServer = %s\n\n' \
+        "$REPOSITORY_NAME" "$REPOSITORY"
+    repositories_section "$profile/pacman.conf"
+} > "$work/pacman.conf"
+mv "$work/pacman.conf" "$profile/pacman.conf"
 
 # ------------------------------------------- the repository the medium carries
 
@@ -138,18 +168,21 @@ repo-add "$carried/$MEDIUM_REPO.db.tar.gz" "$carried"/*.pkg.tar.zst
 say "Writing the live system's pacman.conf"
 mkdir -p "$profile/airootfs/etc"
 {
-    cat "$profile/pacman.conf"
+    options_section "$profile/pacman.conf"
+    package_cache
+    repositories_section "$profile/pacman.conf"
     medium_repository
 } > "$profile/airootfs/etc/pacman.conf"
 
 # And the one an installation without a network is run with: the same options
-# the medium was built under, and the medium's repository as the only one there
-# is. Everything from the top of the file down to the first repository is what
-# `[options]` is, so the section is taken rather than written out again and the
-# two configurations cannot disagree about how packages are checked.
+# the medium was built under, the same cache, and the medium's repository as
+# the only one there is. The options are taken from the profile's file rather
+# than written out again, so the two configurations cannot disagree about how
+# packages are checked or where they are looked for.
 say "Writing the configuration an installation without a network uses"
 {
-    awk '/^\[/ && $0 != "[options]" { exit } { print }' "$profile/pacman.conf"
+    options_section "$profile/pacman.conf"
+    package_cache
     medium_repository
 } > "$profile/airootfs$MEDIUM_CONF"
 

docs/development/008-building-and-publishing.md

@@ -54,7 +54,9 @@ The profile is not kept here. `releng` is archiso's, it moves with archiso, and
 
 The medium's repository is filled by downloading rather than installing: what is wanted is package files, so that an installation with nothing to fetch from has something to install. Every package an answer might ask for is fetched, and not the ones a particular answer would, because an installation without a network cannot go and get the microcode of the processor it turns out to be running on.
 
-Two repositories end up in the live system's `pacman.conf`. Their order separates them: the published one above the official ones, because packages of this project's are this project's wherever else a name appears; and the medium's own below everything, because it is what answers when nothing else can and never what wins while something else can. What is asked of them separates them too — the published one has to be signed and the medium's own is not checked at all, for the reason [Installation ISO](../decisions/018-installation-iso.md) gives. That file is generated from the profile's own rather than written out a second time, so the repositories an image was built from and the ones it installs from cannot come to disagree.
+Two repositories end up in the live system's `pacman.conf`. Their order separates them: the published one above the official ones, because packages of this project's are this project's wherever else a name appears; and the medium's own below everything, because it is what answers when nothing else can and never what wins while something else can. Above means in front of the first repository already in the file, not appended to the end of it, which is where every official one would then be ahead of it. What is asked of them separates them too — the published one has to be signed and the medium's own is not checked at all, for the reason [Installation ISO](../decisions/018-installation-iso.md) gives.
+
+Both configurations also name where packages are looked for before any of them is fetched: the target's own cache, and the medium's repository. That is the same directory that serves the repository, so the files are on the image once and named twice, and an installation with a network does not download a package the medium already holds at the version being installed. That file is generated from the profile's own rather than written out a second time, so the repositories an image was built from and the ones it installs from cannot come to disagree.
 
 A second configuration is written beside the medium's repository, holding that repository and no other. It is what an installation told it has no network is run with, and the installer names it by its path: with it there is nothing to synchronise and nothing to reach for, where the live system's own would try the official repositories first and fail on all of them. It carries the same options the medium was built under, taken from the profile's file rather than written again, and the stanza naming the repository is written once for both.
 

docs/state/000-what-is-built.md

@@ -19,7 +19,7 @@ This document is descriptive. What the tools are for is defined in `../tools/`,
 
 The layout and the reason for it are [Repository Layout](../development/002-repository-layout.md); how the last two are used is [Building and Publishing](../development/008-building-and-publishing.md).
 
-Tests, counted on 2026-09-11: 299 in `src/installer`, 133 in `src/return-message-render`, 85 in `src/dotfiles-sync`, 42 in `src/utils`. Counts move with the work, so treat them as of that date rather than as a fact about the suite. Every suite runs with `baml test` and needs no host, no bridge, no ImageMagick and no privileges. The counts overlap: a suite also runs the tests of every namespace linked into it.
+Tests, counted on 2026-09-11: 304 in `src/installer`, 133 in `src/return-message-render`, 85 in `src/dotfiles-sync`, 42 in `src/utils`. Counts move with the work, so treat them as of that date rather than as a fact about the suite. Every suite runs with `baml test` and needs no host, no bridge, no ImageMagick and no privileges. The counts overlap: a suite also runs the tests of every namespace linked into it.
 
 ## The installer
 
@@ -31,6 +31,8 @@ Tests, counted on 2026-09-11: 299 in `src/installer`, 133 in `src/return-message
 
 **Eleven phases**, orchestrated in order and stopping at the first failure: `prepare_layout`, `bootstrap_base_system`, `configure_localization`, `configure_identity`, `configure_users`, `configure_network`, `configure_swap`, `configure_return_message`, `configure_initramfs`, `configure_bootloader`, `configure_dotfiles`. Nine of them always run; the return message and the dotfiles are present only when the installation was given what they act on, so the list never shows a step that will not happen. Every command's exit status is checked, and a failed file operation is reported by the host and noticed by the orchestrator.
 
+**What the installed machine is left with.** The bootstrap puts on it every tool this project ships except the installer, and the keyring they are checked against; and it writes this project's repository into the target's own `pacman.conf`, above the official ones and as the published address rather than the medium's, so that `pacman -Syu` there updates those tools along with everything else. The medium's copies are also named as a package cache, so an installation with a network fetches only what the medium does not already hold at the version being installed.
+
 **The template package and the theme.** Manifest parsing with format-version checking, message bodies with `{{field}}` references and `[[optional region]]` removal, and loading either from a local directory or from a URL as a `tar` whose entries are listed and refused before extraction if any would land outside the destination — the same path for both, since a theme is delivered like a package. The return-message screen asks for a package, asks for a theme, then asks the fields the package declares and offers the numbers of languages the theme lays out. Both are read and checked, with the values, before the disk is touched. Formats: [Return Message Template Package Format](../tools/oparch-return-message-render/001-template-package-format.md), [Return Message Values Format](../tools/oparch-return-message-render/002-values-format.md) and [Return Message Theme Format](../tools/oparch-return-message-render/003-theme-format.md); the decision behind the theme is [Return Message Themes](../tools/oparch-return-message-render/004-themes.md).
 
 **The pre-boot message phase.** It downloads the logo, asking the operator what to do when the download fails; writes the values into the target as `/etc/opinionatedarch/return-message.yaml`, composed by the same namespace that parses that format so the two cannot disagree; installs the project's Plymouth theme; runs `oparch-return-message-render` against the file it just wrote, with the theme in the target as its output; and makes that theme the default. It runs before the initramfs is built, and does nothing at all when no return message was asked for.

docs/tools/oparch-installer/002-inputs-and-bootstrap-baseline.md

@@ -84,13 +84,21 @@ Installed with `pacstrap`:
 - `sudo`
 - `networkmanager`
 - `ipxe`
+- `oparch-assets`
+- `oparch-return-message-render`
+- `oparch-dotfiles-sync`
+- `oparch-keyring`
 - `zram-generator` (if the zram swap size is greater than zero)
 - `intel-ucode` (if selected as the ucode package)
 - `amd-ucode` (if selected as the ucode package)
 - `nvidia-open` (if GPU driver is `nvidia-open`)
 - `plymouth` (if pre-boot return message is enabled)
 
-They come from the repositories the live environment is configured with, the official ones first and the medium's own last; or, when the installation was told it has no network, from the medium's own configuration, which names the repository the medium carries and nothing else. Which of the two an installation draws from is settled in [Installation ISO](../../decisions/018-installation-iso.md), and the answer that settles it is prompt 2.
+The four this project publishes are every tool it ships except `oparch-installer`, which runs from a live environment and has no use on a machine that is installed, together with the keyring that lets the rest be updated from where they came from. What that is, and why the repository sits above the official ones on the installed system, is [Package Repository](../../decisions/016-package-repository.md); the installation writes it into the target as the published repository and never as the one the medium carries, which will not be there once the machine is running.
+
+They come from the repositories the live environment is configured with, this project's first, the official ones after it and the medium's own last; or, when the installation was told it has no network, from the medium's own configuration, which names the repository the medium carries and nothing else. Which of the two an installation draws from is settled in [Installation ISO](../../decisions/018-installation-iso.md), and the answer that settles it is prompt 2.
+
+Where they are looked for is not where they come from. The medium's own repository is also named as a package cache, so a package whose exact version is already on the medium is taken from there instead of being fetched, and only what the machine does not already have is downloaded. What is fetched is kept in the target's cache; the live environment's own directories are memory, and a bootstrap is more of it than a small machine has.
 
 ### Netboot Recovery Binary
 

packages/oparch-installer/PKGBUILD

@@ -1,5 +1,5 @@
 pkgname=oparch-installer
-pkgver=0.1.0dev4
+pkgver=0.1.0dev5
 pkgrel=1
 pkgdesc="Installs OpinionatedArch onto a machine, from a live environment"
 arch=('x86_64')

src/installer/baml_src/config_file.baml

@@ -458,6 +458,9 @@ function packaged_files() -> root.common.RecordingFiles {
                 "[Trigger]\nTarget = boot/amd-ucode.img\n");
     files.write("/assets/pacman-hooks/90-oparch-microcode-intel.hook",
                 "[Trigger]\nTarget = boot/intel-ucode.img\n");
+    //# what the `pacman` package leaves in the target, which is there by the
+    //# time the bootstrap writes this project's repository into it
+    files.write("/mnt/etc/pacman.conf", packaged_pacman_conf());
     files
 }
 

src/installer/baml_src/network.baml

@@ -216,11 +216,18 @@ function reaches_repository(shell: root.common.Shell) -> bool {
                            repository_probe()]).exit_code == 0
 }
 
+/// Where this project publishes its packages. It is asked about here and
+/// written into the installed system by the bootstrap, and both say it from
+/// here so that they cannot come to name different servers.
+function package_repository() -> string {
+    "https://packages.oparch.iokode.dev"
+}
+
 /// What is asked. The database rather than the bare host, because a name that
 /// resolves and a server that answers are different things, and the second is
 /// the one that matters.
 function repository_probe() -> string {
-    "https://packages.oparch.iokode.dev/oparch.db"
+    `${package_repository()}/oparch.db`
 }
 
 /// Where the medium keeps the pacman configuration that resolves against the