hq/01-RESEARCH/025-how-a-module-plugs-into-the-shell/00-overview.md

---
status: graduated
initiated: 2026-10-04
touches:
  - 02-DECISIONS/0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md
  - 02-DECISIONS/0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md
  - 02-DECISIONS/0177-a-unit-may-be-user-scoped-and-the-service-manager-is-a-node-seat.md
  - 02-DECISIONS/0126-a-module-declares-its-own-seats.md
  - 02-DECISIONS/0102-the-mesh-writes-into-a-shared-file-never-over-it.md
  - 02-DECISIONS/0182-inside-a-home-the-mesh-owns-what-it-places-and-holds-the-rest-as-found.md
  - 02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md
  - 03-DESIGN/01-to-be/27-a-module-requires-the-mesh-resolves.md
  - 03-DESIGN/01-to-be/31-a-module-declares-its-fail2ban-jail.md
  - 03-DESIGN/01-to-be/37-the-operators-machine.md
  - 03-DESIGN/01-to-be/38-building-the-operators-machine.md
  - 04-ISSUES/168-a-setting-reaches-every-file-and-contribution/00-report.md
became:
  - 02-DECISIONS/0203-the-accounts-environment-is-one-modules-and-every-module-contributes-to-it.md
  - 02-DECISIONS/0204-a-module-contributes-shell-code-to-the-login-shell-in-named-slots.md
  - 02-DECISIONS/0205-software-the-distribution-does-not-package-ships-as-a-pinned-archive-of-the-module.md
  - 03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md
---

# 025 — How a module plugs into the operator's shell

## What is investigated

The shell module writes the mesh's part of the account's shell startup file. But the shell is not the
only module that needs a line there. A prompt theme loads itself from it. A language version manager
sets a variable and sources its loader. A toolchain puts its directory on `PATH`. A desktop module
names the browser. Today all of these sit in one hand-written file, and the shell module as written
carries some of them in its own block and loads others only "if a module placed them". Nothing says
how they get placed.

This effort asks four things:

1. **How a module contributes to the shell**: what it declares, who composes it, and in what order it
   lands.
2. **Where the environment lives.** Variables and `PATH` entries are facts about the account, not
   lines of one shell's syntax. They should reach every shell (interactive or not), the login shell's
   `execute` verb, and programs a graphical session starts.
3. **Where the operator's own lines go,** so that assigning the shell module loses nothing the
   machine does today.
4. **Which part of a file the mesh owns.** ADR 0174 calls the kept region the operator's; the host and
   to-be 38 implement the inverse (the mesh owns a marked block, and everything outside it is the
   operator's). The record this becomes says which.

## Why

Rolling out the shell module (to-be 38 WP5) was stopped on 2026-10-04 after a review of what assigning
it would do. Measured in [01](01-what-the-shell-file-holds-today.md):

- Every machine carries the same predecessor-written startup file, so the module's block would be
  appended after its own older copy and everything would run twice.
- The block drops lines the machines rely on today.
- Nothing installs the prompt theme or the plugins the block loads.
- The `execute` verb runs a non-interactive login shell, which never reads the file the block is
  written into.

The operator's direction: other modules must be able to plug themselves into the shell; the prompt
becomes its own module; assigning the shell module must lose no functionality; and the environment,
`PATH` above all, needs an answer of its own.

## What it touches

- The manifest. A contribution to the shell is either a new use of the existing `contributes` /
  `receives` pair or a new gathered field like `jails` (to-be 31).
- The controller's composition, if the controller assembles the text.
- The `login-shell` seat (ADR 0176): what a holder must do with what is contributed to it, and
  whether a module or the mesh declares the seat. Possibly a new seat for the environment, beside it
  and beside the service manager's (ADR 0177). Research 023 asks the related question of a seat
  naming the files its holder owns.
- ADR 0174's wording of the kept region, and ADR 0182's classification of the paths under a home.
- The zsh module, and the modules this makes possible: an environment module, the prompt, a version
  manager, a toolchain.

## Where it stands

The operator proposed a separate **environment module**: one module, holding a mesh seat of its own,
that alone writes the account's environment. It writes a file that shells source and the service
manager's user environment, from the variables and `PATH` entries every other module contributes to
it. That is the starting position for the environment ([02](02-how-a-module-plugs-in.md) §1, option
E6). It leaves the shell's contribution as shell code only (§2), addressed to the `login-shell` seat,
which moves into the mesh's own seat set beside the new `node-environment` (§6).

Graduated on 2026-10-04 with one change from the starting positions: the controller, not the
environment module's own code, renders the environment into the module's files, so that the result
is in the declaration before a machine applies it ([ADR 0203](../../02-DECISIONS/0203-the-accounts-environment-is-one-modules-and-every-module-contributes-to-it.md),
option 6b).

## Documents

- [01 — What the shell file holds today](01-what-the-shell-file-holds-today.md): evidence.
- [02 — How a module plugs in](02-how-a-module-plugs-in.md): the options and the starting position.