valise-sh 0.2.0 → 0.3.0

package/docs/module-abi.md

@@ -1,15 +1,17 @@
-# Shell-profile module ABI
+# Module ABI
 
-This document defines the metadata consumed by the loader before it sources
-module bodies. Metadata is data: discovery does not execute module
-implementations to learn their names, dependencies, or supported runtimes.
+This document defines module metadata and the rules the compiled plans and
+the loaders apply to it. Metadata is data: valise never executes a module to
+learn its name, dependencies, or supported shells.
 
 ## Metadata file format
 
 Module metadata lives in `module.d/*.meta` as UTF-8 text with one `key=value`
 field per line. Blank lines and `#` comments are ignored. Values are plain text;
 there is no shell quoting, interpolation, command substitution, glob expansion,
-or `eval` phase.
+or `eval` phase. Each field may appear once: a repeated key is rejected rather
+than letting the last value win. An unknown field is rejected, and so is
+`updates`, which was removed in 0.3.0.
 
 Required fields:
 
@@ -19,8 +21,8 @@ Required fields:
 | `shells` | Space-separated supported shell identifiers. |
 | `platforms` | Space-separated supported platform identifiers. |
 | `side_effect` | Startup/install/update side-effect class. |
-| `load` | Repository-relative path to the module body. |
-| `requires` | Required when the module is a **meta module** (see below). |
+| `load` | Path to the module body, relative to the module's source directory. Absent for a **meta module** (see below). |
+| `requires` | Required for a meta module. |
 
 Optional fields:
 
@@ -29,7 +31,9 @@ Optional fields:
 | `requires` | Space-separated required dependency module identifiers. |
 | `optional` | Space-separated optional dependency module identifiers. |
 | `exports` | Space-separated exported command/function identifiers. |
-| `updates` | Space-separated update identifiers registered by the consuming project. |
+| `commands` | Space-separated exports a built release publishes as commands on PATH. |
+| `executables` | Space-separated module-relative paths of scripts published as commands. |
+| `tests` | Space-separated module-relative test scripts that `valise test` runs. |
 | `version` | Optional module version used to reject version skew across roots. |
 
 ## Meta modules
@@ -49,12 +53,11 @@ an export on a meta module is rejected.
 name=profile_main
 version=1.0.0
 side_effect=read-only
-requires=contrib_path contrib_editor
+requires=valise_path valise_editor
 optional=
-shells=bash zsh ksh
+shells=posix
 platforms=any
 exports=
-updates=
 ```
 
 At least one of `load` or `requires` is required: a module with neither a
@@ -75,67 +78,74 @@ whitespace inside one identifier, path separators, quotes, shell metacharacters,
 glob characters, and control characters are invalid. Invalid identifiers are
 rejected before the loader can build function names or source a body.
 
-Accepted `shells` values are `sh`, `bash`, `zsh`, `ksh`, and `fish`.
-`shells=sh` means the module body is POSIX-shell syntax, and it is loaded by
-**every POSIX shell** — `sh`, `bash`, `zsh`, `ksh`, and dash — because those
-shells all run POSIX syntax. The engine classifies a running shell as `bash`,
-`zsh`, or `ksh` when it can prove it, and as `sh` otherwise (dash, BusyBox
-ash, and any other POSIX shell); `shells=sh` matches both the `sh` class and
-the specific classes, so a `shells=sh` module loads in all of them. Write
-portable bodies for `shells=sh` and you cover every POSIX shell at once.
-
-`fish` is the exception: it selects the native Fish surface under
-`lib/fish/`, and the Fish loader never sources POSIX shell bodies. A module
-whose `shells=` list does not contain `fish` is skipped under Fish rather
-than failed — a directly requested module fails closed in strict mode.
-
-The engine ships a generic Fish adapter at `entrypoints/fish/profile.fish` as
-the reference implementation of this handshake: it sets
-`_sp_fish_loader_bootstrap_mode` and `_sp_fish_loader_bootstrap_seeds`, then sources `loader.fish`. The loader
-consumes and clears that request and publishes a fresh
-`_sp_fish_loader_bootstrap_status`; callers must fail closed when the marker is
-absent. Fish provider precedence is project-native, engine-native, engine
-generic, and project generic. Duplicate providers are valid only when their
-metadata and native bodies are byte-identical; conflicting metadata or bodies
-is rejected before any body is sourced. Public adapters must not execute the
-generated Fish plan directly.
+Accepted `shells` values are `posix`, `sh`, `bash`, `zsh`, `ksh`, and
+`fish`. Each running POSIX shell belongs to one class: `bash`, `zsh`, or
+`ksh` when the shell can be proven to be that shell, and `sh` for every
+other POSIX shell (dash, BusyBox ash, and so on). The values match classes
+as follows:
+
+- `posix` matches every POSIX class: `sh`, `bash`, `zsh`, and `ksh`. Use it
+  for a body written in portable shell.
+- `sh` matches only the `sh` class. Combine it with the shells the body also
+  supports: `shells=sh bash ksh` loads in dash, bash, and ksh, and is skipped
+  in zsh, for a body that needs word splitting zsh does not do.
+- `bash`, `zsh`, and `ksh` match only that class.
+- `fish` selects the native Fish runtime. Fish never sources a POSIX body,
+  and no POSIX value matches Fish.
+
+A module whose shells do not include the running class is skipped; a bundle
+root, or a module a root requires, that does not support its shell is an
+error.
+
+In a built release, the native Fish loader resolves the release's Fish roots
+(`roots_fish=` in `valise-release.conf`) against the release's `module.d/`,
+each `layers/<provider>/module.d/`, and `valise/module.d/`, in that order.
+`runtime/fish/profile.fish` is the adapter the Fish hook sources: it sets
+`_sp_fish_loader_bootstrap_mode` and `_sp_fish_loader_bootstrap_seeds`,
+sources `runtime/fish/loader.fish`, and requires the
+`_sp_fish_loader_bootstrap_status` marker the loader publishes, failing
+closed when it is absent. Duplicate providers of one name are valid only when
+their metadata and Fish bodies are byte-identical.
 
 Supported `platforms` values are `any`, `darwin`, `linux`, `bsd`, `freebsd`,
 `openbsd`, and `netbsd`. `platforms=any` matches every supported platform.
 Specific platform values are ORed: `platforms=darwin linux` matches macOS or
 Linux, not BSD.
 
-## Multi-root layer search path
-
-The loader resolves modules across a priority-ordered root list. The primary
-root is the `sp_loader_load_modules <root> ...` argument and always wins for
-metadata it provides. `VALISE_MODULE_PATH` lists additional layer roots as a
-colon-separated path, searched in priority order after the primary root.
-With it unset the behavior is exactly the historical single-root
-behavior.
-
-Semantics, enforced by `tests/loader/multi-root.test.sh`:
-
-- Every search-path element must be a non-empty readable, executable directory; empty
-  elements, missing, unreadable, or unsearchable directories are fail-closed
-  data errors (element validation runs with globbing disabled, so
-  glob-metacharacter elements are not expanded and must name a real readable,
-  executable directory). Identical duplicate elements are deduplicated
-  at validation; priority belongs to the first occurrence.
-- A module name present in multiple roots must have identical metadata and
-  body bytes. Identical copies resolve to the highest-priority root; any
-  difference is an error naming both paths. A layer cannot silently replace
-  a module from the primary root or an earlier layer.
-- A module provided only by a layer root must carry the `contrib_` name
-  prefix. Non-prefixed layer-only modules fail closed with a diagnostic
-  naming the layer.
-- Module bodies load from the root that provided the metadata; cross-root
-  dependency discovery works in both directions (layer modules may require
-  primary modules), and deterministic `sort -u` + topological ordering is
-  preserved across roots.
-- The duplicate-export fail-closed check is global across roots: a layer
-  module may not re-export an identifier already declared by a loaded module.
-- No loader-private state leaks after multi-root loads.
+## Layers
+
+A project composes provider modules by vendoring the provider's tree as
+`layers/<provider>/` (its `module.d/` and bodies). Every module in a layer
+uses the `contrib_` prefix, and the `valise_` prefix belongs to the engine.
+Dependencies resolve by name: the same source first, then the only module
+with that name; a name defined in several sources must be written as
+`name@source` where it is used as a root or an exclusion. A built release
+copies the layer modules it loads to `layers/<provider>/`, and one manifest
+covers the project, layer, and engine files together.
+
+To update a provider, copy a reviewed revision into `layers/<provider>/`,
+review the diff, and rebuild; record the provider revision beside it if you
+need to know later which one you have. The manifest proves that the
+installed files match the release, not who wrote them.
+
+### The development loader's search path
+
+The POSIX loader in `lib/loader.sh`, used by `entrypoints/profile.sh` from an
+engine checkout, resolves modules across a priority-ordered root list
+instead: the primary root first, then the colon-separated
+`VALISE_MODULE_PATH`. Its rules, enforced by
+`tests/loader/multi-root.test.sh`:
+
+- Every element must be a non-empty, readable, searchable directory. An
+  empty element, a missing directory, a newline, or any of the glob
+  characters `[`, `?`, and `*` is rejected. Duplicate elements are
+  deduplicated; the first occurrence keeps its priority.
+- A module present in several roots must have identical metadata and body
+  bytes. Identical copies resolve to the highest-priority root; any
+  difference is an error naming both paths.
+- A module provided only by a layer root must carry the `contrib_` prefix.
+- Bodies load from the root that provided the metadata. Dependencies resolve
+  across roots in both directions, and the duplicate-export check is global.
 
 ## Versioning
 
@@ -143,10 +153,11 @@ Shared modules carry an optional `version` field so independent releases
 of the same name can be told apart. The value must start with a digit
 and contain only digits, letters, `.`, `_`, `-`; an empty value means
 unversioned. Providers should bump the version for a breaking change.
-Consumers vendor a specific provider snapshot; the loader does not resolve
-version ranges. See [Cross-repo composition](#cross-repo-composition).
+Consumers vendor a specific provider snapshot; nothing resolves version
+ranges. See [Layers](#layers).
 
-Enforcement, in both the POSIX loader and the native Fish loader:
+Enforcement, where one name has several providers (the development loader's
+roots, or the Fish loader's providers):
 
 - The same name with different valid versions across roots fails closed
   with a version-skew diagnostic naming both versions and both paths,
@@ -160,32 +171,6 @@ A versioned record that disagrees with itself is not a version at all:
 malformed versions are rejected by `sp_metadata_read` before any body
 is sourced.
 
-## Cross-repo composition
-
-The supported composition is a primary consumer root plus one
-version-pinned layer root per provider.
-The provider tree is vendored under `layer/<name>/` of the release
-(preserving its internal `module.d/` + `modules/` layout), and a single
-manifest covers the whole closure, so `release verify` checks consumer
-and provider bytes together before anything is sourced.
-
-- Pinning: record the provider source and revision beside the vendored
-  bytes (the e2e example writes `layer/shared/layer-pin.txt` from
-  `git rev-parse HEAD` at vendor time). Re-pinning means copying the
-  provider at a new revision, reviewing the diff, and rebuilding the
-  manifest. Pin by git SHA and review the diff; the seal proves the
-  release matches its manifest, not who authored it.
-- Loading: the consumer sets `VALISE_MODULE_ROOT` to the release and
-  `VALISE_MODULE_PATH` to the layer directory inside it. Deployed login
-  snippets carry only the primary root; the layer path is a consumer
-  setting applied when sourcing the entrypoint.
-- Naming: layer-only modules must carry the `contrib_` prefix, and
-  same-name modules across roots must be byte-identical or the load
-  fails closed naming both paths. Dependencies resolve across the
-  boundary in both directions: layer modules may require primary
-  modules, and primary modules may follow optional dependencies into
-  the layer.
-
 ## Runtime detection contract
 
 The loader classifies the running shell and platform before matching module
@@ -270,30 +255,42 @@ Only the module for the running platform loads. The other is skipped without a
 message, because its absence is expected. The POSIX loader and compiled plans
 follow the same rules.
 
-`exports` lists public commands or shell functions the module declares. The loader
-uses this list for post-load export checks and failure cleanup; project catalogs
-and wrapper manifests use it for documentation and registration. An exported name
+`exports` lists the public functions the module defines. Plans and loaders use
+it for the pre-load conflict check, the post-load check, and failure cleanup.
+An exported name
 must be defined by the module body before the module is considered
 successfully loaded. An export must name a function, so shell reserved words
 (`case`, `do`, `done`, `elif`, `else`, `esac`, `fi`, `for`, `if`, `in`,
 `then`, `until`, `while`, and `time`) are rejected.
 
-`updates` lists update registrations declared by the module. Each value is an ABI
-identifier that maps one-to-one to a row in the project update manifest. The
-project validator rejects missing, duplicate, or unowned registrations. URL,
-destination, digest, trust policy, and rollback state belong in that manifest;
-module metadata states registration only and does not execute update lifecycle work.
-
-## Update channel for shared modules
-
-Shared modules are vendored snapshots. `valise` does not fetch provider
-updates. To update a provider, vendor a reviewed revision and rebuild the
-release manifest. Bump `version=` when making an incompatible module change;
-the loader rejects conflicting versions of the same module across roots.
-The manifest detects changes to installed files but does not authenticate
-their author; see [installation.md](installation.md). The `updates=` field
-is registration for a consuming project's separate update manifest, not an
-engine update mechanism.
+### Published commands
+
+`commands` names exports that should also run as ordinary commands, from any
+program and not only from an interactive shell. Every entry must also appear in
+`exports`. `executables` names standalone scripts in the module's directory;
+each is published under its file name, which must start with a letter, digit,
+or underscore and contain only letters, digits, `.`, `_`, and `-`. The
+metadata field `updates` was removed in 0.3.0; a metadata file that still sets
+it is rejected.
+
+`valise build` turns both into entries under the release's `bin/`:
+
+- For a module with `commands`, it compiles `plans/commands/<module>.sh`, a
+  plan whose only root is that module, for the module's command shell: `sh`
+  when the module supports `posix` or `sh`, otherwise the first of `bash`,
+  `zsh`, and `ksh` it lists. Each command gets a launcher `bin/<command>` that
+  runs under that shell, loads the plan in strict mode from the release that
+  contains it, restores the caller's `VALISE_MODE`, and calls the function
+  with the command's arguments. The function's exit status is the command's.
+- Each `executables` path is copied to `bin/<file name>` and keeps its own
+  interpreter line.
+
+The plan's closure ships in the release even when no shell bundle loads it.
+A Fish-only module cannot declare `commands`; it may declare `executables`.
+Two modules that publish the same command name, from either field, fail the
+build. `valise-release.conf` lists the published names in `commands=`.
+Installation puts a stub for each name on PATH; see
+[installation.md](installation.md#published-commands).
 
 ## Side-effect phases
 
@@ -315,12 +312,13 @@ before ordinary source invokes a load path.
 
 ## Capability layer available to modules
 
-The POSIX entrypoint sources `lib/capabilities.sh` before it calls the loader.
-Portable module bodies may therefore depend on `sp_cap_*` helpers without
-sourcing OS-specific files themselves. This is the ABI boundary for behavior that
-varied in the flat monolith: CPU count, file mtime, temp directories/files, command
-lookup, OS detection, canonical path containment, symlink-component rejection,
-Homebrew path discovery, secure local-bin permission checks, and background
+Every plan sources the capability prelude (`runtime/capabilities.sh` in a
+release, `lib/capabilities.sh` in the engine) before any module, and the
+development entrypoint does the same before the loader. Module bodies may
+therefore call the `sp_cap_*` helpers without sourcing platform files
+themselves: CPU count, file mtime, temporary directories and files, command
+lookup, OS detection, canonical path containment, symlink-component
+rejection, Homebrew discovery, secure local-bin checks, and background
 process launch.
 
 **The helpers stay available after the profile loads.** A compiled plan
@@ -344,15 +342,15 @@ Read-only/status paths may degrade only by quietly skipping unsupported details
 or by returning a clear nonzero status with a diagnostic from the caller.
 
 Platform modules under `modules/platform/` are thin wrappers around the library.
-They expose stable module dependencies (`platform_posix`, `platform_macos`,
-`platform_linux`, and `platform_bsd`) while keeping compatibility logic in one
+They expose stable module dependencies (`valise_platform_posix`, `valise_platform_macos`,
+`valise_platform_linux`, and `valise_platform_bsd`) while keeping compatibility logic in one
 library.
 
 ## Load target and loader mode
 
-For file-backed modules, `load` is the repository-relative shell file sourced by
-the loader after metadata validation, dependency sorting, shell/platform matching,
-and phase side-effect checks have passed. The ABI has no unload hook: the loader
+For file-backed modules, `load` is the shell file sourced after metadata
+validation, dependency ordering, shell and platform matching, and the
+side-effect checks have passed. The ABI has no unload hook: the loader
 does not implement module rollback or unload semantics.
 
 A meta module has no `load`; it has `requires` and no body. Nothing is
@@ -388,7 +386,8 @@ Permissive mode reports the affected module and continues with unrelated modules
 
 ## Path fields
 
-`load` paths are repository-relative implementation paths. Absolute
+`load`, `executables`, and `tests` paths are relative to the module's source
+directory (the project root, `layers/<provider>/`, or the engine). Absolute
 paths, `..` path segments, spaces, quotes, shell metacharacters, and glob
 characters are invalid. Reading metadata must not source these paths.
 

package/docs/projects.md

@@ -0,0 +1,249 @@
+# Projects, bundles, variants, and builds
+
+This document describes a valise project: the files it contains, how
+`valise compile` and `valise build` turn them into plans and a release, and
+how those commands fail. [module-abi.md](module-abi.md) covers the metadata
+format; [installation.md](installation.md) covers what happens to a release
+once it is built.
+
+## The project layout
+
+A project is a directory that holds `valise.conf`:
+
+```
+valise.conf          project settings
+module.d/            primary modules: <name>.meta
+modules/             primary module bodies (any layout below modules/)
+layers/<provider>/   vendored provider layers (optional)
+  module.d/          layer modules: contrib_<name>.meta
+  modules/           layer module bodies
+bundles.tsv          the root modules of each bundle, per shell
+variants.tsv         build variants and what each leaves out (optional)
+build/               build output; keep it out of version control
+```
+
+`valise new [dir]` writes this layout with a POSIX seed module
+`profile_main`, a Fish seed module `profile_main_fish`, a `bundles.tsv` with
+`sh`, `bash`, `zsh`, `ksh`, and `fish` rows, `variants.tsv`, and a
+`.gitignore` for `build/`.
+
+Project commands find the project by walking up from the working directory to
+the first directory that holds `valise.conf`. `valise -C <dir> <command>` runs
+a command as if it had been started in `dir`.
+
+`valise.conf` has one `key=value` per line. Blank lines and `#` comments are
+ignored; an unknown or repeated key is an error.
+
+| Key | Meaning |
+|---|---|
+| `bundle` | Default bundle for build, apply, compile, and run (default `default`). |
+| `variant` | Default variant (default `default`). |
+| `requires_valise` | Oldest valise version that may build the project, such as `0.3.0`. An older valise refuses with `this project requires valise >= ...`. |
+| `lint_layer_forbid` | Extended regular expression that must not match anything under `layers/` (case-insensitive). `valise lint` enforces it; use it to keep personal or employer material out of a layer you share. |
+
+A layer's directory name is made of letters, digits, `_`, `-`, and `.`, and
+may not start with `.` or contain `..`. Metadata and bodies must be regular
+files reached without a symlink.
+
+## Modules and the registry
+
+The `.meta` files are the only source of truth. valise reads them as data,
+never by sourcing them. Each build collects three groups of modules:
+
+1. the project's `module.d/`, with source `module.d`;
+2. each `layers/<provider>/module.d/`, with source
+   `layers/<provider>/module.d`;
+3. the engine's own modules, with source `valise`.
+
+The engine modules (`valise_path`, `valise_editor`, `valise_history`,
+`valise_pager`, `valise_xdg`, and the `valise_platform_*` modules) are always
+available. They ship in a release only when the release loads them. The
+`valise_` prefix is reserved for them, and every layer module must use the
+`contrib_` prefix.
+
+`valise registry [path]` prints the table valise builds from these files, for
+inspection. It is internal: nothing reads a saved copy, so do not commit one.
+The table is tab-separated, with one header row and one row per module, in
+a fixed order: primary modules, then each layer, then the engine, each in
+C-locale name order.
+
+| # | Column | Meaning |
+|---|---|---|
+| 1 | `name` | Module identifier. |
+| 2 | `version` | Version string; empty means unversioned. |
+| 3 | `side_effect` | Side-effect class. |
+| 4 | `requires` | Required dependencies. |
+| 5 | `optional` | Optional dependencies. |
+| 6 | `shells` | Shell classes. |
+| 7 | `platforms` | Platforms. |
+| 8 | `exports` | Exported functions. |
+| 9 | `load` | Body path relative to the module's source directory; empty for a meta module. |
+| 10 | `commands` | Exports published as commands. |
+| 11 | `executables` | Scripts published as commands. |
+| 12 | `tests` | Test scripts for `valise test`. |
+| 13 | `source` | `module.d`, `layers/<provider>/module.d`, or `valise`. |
+
+Building the table also validates it. A `name` that differs from its file
+name, a missing body, executable or test, a symlink, a misplaced prefix, or
+invalid metadata stops the command and names the file.
+
+A module reference is a bare name or a qualified `name@source`. A bare
+dependency resolves to the module with that name in the same source when
+there is one, otherwise to the only module with that name. A bare bundle root
+or exclusion resolves to the primary module when there is one, otherwise to
+the only module with that name; when several sources define the name, qualify
+it.
+
+## Bundles: the root modules for each shell
+
+`bundles.tsv` is tab-separated: bundle, shell, and a space-separated list of
+root modules. The first row may be a header.
+
+```
+bundle	shell	roots
+default	sh	profile_main
+default	bash	profile_main profile_bash
+default	zsh	profile_main
+default	ksh	profile_main
+default	fish	profile_main_fish
+work	bash	profile_main profile_work
+```
+
+The shell column is one of `sh`, `bash`, `zsh`, `ksh`, and `fish`. `sh` is the
+plan for any POSIX shell that is not bash, zsh, or ksh, such as dash or
+BusyBox ash. A bundle without a row for a shell loads nothing there.
+
+Roots are starting points. The plan loads each root's whole closure of
+`requires` and available `optional` dependencies, in dependency order.
+`valise explain-bundles [--bundle=<name>] [--variant=<name>]` prints each
+bundle's roots and ordered closure per shell, with each module's source.
+
+A root, and every module it requires, must support the shell and the
+platform it runs on: in strict mode an unsupported platform is a failure. A
+module that exists only for some platforms belongs behind an optional edge.
+Write an aggregator whose `optional=` lists the per-platform modules and use
+the aggregator as the root; the module for the running platform loads, and
+the others are skipped without a message.
+
+## Variants: what to leave out
+
+`variants.tsv` is tab-separated: variant name, description, and a
+space-separated list of excluded modules. Without the file, the only variant
+is `default`, which excludes nothing.
+
+```
+variant	description	excluded
+default	All project modules	
+lean	No editor defaults	valise_editor
+```
+
+Each exclusion must resolve to exactly one module; an unknown or ambiguous
+exclusion is an error. An excluded module is removed from every closure, and
+its optional edges are dropped. **If a remaining module requires an excluded
+module, the build fails**, naming both; exclude the dependents too. Nothing is
+removed silently.
+
+`valise explain-variant [--bundle=<name>] [name]` shows a variant's
+description, its exclusions, and how many of the bundle's roots it removes
+per shell. The bundle chooses the roots, and the variant then removes
+modules from what they reach.
+
+## `valise compile`
+
+```sh
+valise compile [--bundle=<name>] [--variant=<name>] <output-dir>
+```
+
+Compile writes `<output-dir>/<shell>.sh` for each POSIX shell the bundle has
+roots for, and nothing else. The output directory must be empty or absent;
+compile stages beside it and publishes only after every plan compiled.
+
+A plan is a POSIX shell file:
+
+```
+# valise-plan-v2
+# Generated by valise compile; DO NOT EDIT.
+# plan=bash
+# roots=profile_main
+# order=valise_path profile_main
+```
+
+The header names the format, the shell, the roots, and the resolved load
+order. Sourced with `VALISE_MODULE_ROOT` naming a release, the plan:
+
+- reads `VALISE_MODE` (`strict` or `permissive`; default `strict`);
+- probes the platform once and gates each module by `platforms=`;
+- sources `runtime/capabilities.sh`, so the `sp_cap_*` helpers stay available
+  to module functions afterwards;
+- refuses to load a module whose declared export already exists as an alias,
+  function, or builtin (an export may shadow a command on PATH), and checks
+  after loading that each export is defined;
+- skips a module whose required dependency failed or was skipped, and says
+  which;
+- in strict mode, returns nonzero at the first failure among the roots and
+  everything they require;
+- in permissive mode, reports each failure, continues with unrelated
+  modules, and returns zero;
+- loads an optional dependency first when it can; its absence never affects
+  the module that declared it;
+- with `VALISE_RELOAD=1`, removes the plan's declared exports first, so the
+  plan can be sourced again.
+
+Compile fails before writing anything when the variant or bundle is unknown,
+an exclusion or root does not resolve, a variant exclusion breaks a required
+dependency, a module in a closure has a side-effect class that is not safe at
+startup (`generated-file`, `update-network`, or `install-time`), or a module
+is not representable as plan source.
+
+## `valise build`
+
+```sh
+valise build [--bundle=<name>] [--variant=<name>] [out]
+```
+
+Build produces an installable release tree at `build/release`, or at `out`,
+which must then be empty or absent. The tree contains:
+
+```
+valise-release.conf                   format=2, valise_version, bundle, variant,
+                                      roots_<shell>=, modules=, commands=
+manifest.tsv                          the release manifest
+plans/<shell>.sh                      one plan per POSIX shell with roots
+plans/commands/<module>.sh            a plan per module that publishes commands
+bin/<command>                         command launchers and executables
+runtime/capabilities.sh               the capability prelude
+runtime/fish/{metadata,loader,profile}.fish   when the bundle has fish roots
+module.d/, modules/...                primary modules some shell loads
+layers/<provider>/module.d, ...       layer modules some shell loads
+valise/module.d, valise/modules/...   engine modules some shell loads
+```
+
+Only modules in some shell's closure are copied, with their metadata. A
+module that a variant excludes, or that no root reaches, is absent from the
+release, together with its body. The Fish runtime resolves the Fish roots
+recorded in `valise-release.conf` against the copied metadata when Fish
+starts. See [module-abi.md](module-abi.md#published-commands) for `bin/`.
+
+Directories are `0755`, files `0644`, and `bin/` entries `0755`. Build
+stages beside the destination and publishes only after the tree and its
+manifest are complete. A previous `build/release` is moved aside first and
+put back if publication fails, so a failed build leaves the previous output
+in place. Building the same project twice produces byte-identical output.
+
+## `valise apply` and `valise status`
+
+`valise apply [--bundle=<name>] [--variant=<name>] [--no-integration]
+[--dry-run]` builds to `build/release`, installs it, writes the shell
+integration and command stubs, and verifies the active release. Running it
+again changes nothing. `--dry-run` stops after the build and prints what
+install would change; see [installation.md](installation.md).
+
+`valise status` reports the project defaults, the integration in each startup
+file, the bundle, variant, and valise version the active release was built
+with, and whether the active release matches `build/release`.
+
+## Checking a project
+
+`valise lint` and `valise test` check a project without installing it, and
+`valise run` loads modules into a throwaway shell; see
+[contrib-modules.md](contrib-modules.md#checking-and-testing-modules).