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

status, initiated, touches, became

status	initiated	touches	became
active	2026-10-04	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/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

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:

• 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. 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: the prompt, a version manager, a toolchain.

Documents

• 01 — What the shell file holds today: evidence.
• 02 — How a module plugs in: the options and the starting position.