diff --git a/01-RESEARCH/029-the-agent-configured-through-its-module/00-overview.md b/01-RESEARCH/029-the-agent-configured-through-its-module/00-overview.md index 3e90486..1863055 100644 --- a/01-RESEARCH/029-the-agent-configured-through-its-module/00-overview.md +++ b/01-RESEARCH/029-the-agent-configured-through-its-module/00-overview.md @@ -26,6 +26,16 @@ including a machine that joins later. The mechanism is the one the module alread servers: the registration is kept in the module's state on the bus, and each machine's instance writes what applies to it. The operator chose the plugin route on the day this effort opened. +**Three scopes** (the operator's direction, the same day): + +- **mesh:** in the mesh's plugin and the managed files, on every machine; +- **node:** the same places, rendered for one machine or a list of them; +- **home:** placed in the operator account's own agent directory on a machine, beside what the + person writes there by hand. + +Instructions follow the same scopes: the mesh's piece, the node's piece, then further customisation per +machine. See [03](03-options.md). + ## Why The vendor gives the agent a machine-wide directory for its settings, its tool servers and one diff --git a/01-RESEARCH/029-the-agent-configured-through-its-module/03-options.md b/01-RESEARCH/029-the-agent-configured-through-its-module/03-options.md index c73e45e..7217d7f 100644 --- a/01-RESEARCH/029-the-agent-configured-through-its-module/03-options.md +++ b/01-RESEARCH/029-the-agent-configured-through-its-module/03-options.md @@ -3,6 +3,40 @@ The route is chosen: a plugin the mesh serves. What is left open is where each kind of item goes, how it is registered and kept, and what the module does about what it finds in the homes. +## Scopes (the operator's direction, 2026-10-04) + +The plugin is not the only place the module manages. **The agent's configuration is managed at three +scopes, and each item is registered at one of them:** + +| scope | where it lands | reaches | +|---|---|---| +| **mesh** | the mesh's plugin, and the mesh's part of the managed files | every machine running the agent, including one that joins later | +| **node** | the same plugin and managed files, as rendered on that machine | one machine, or a list of them | +| **home** | the operator account's own agent directory on a machine (`~/.claude`) | that account on that machine | + +Each machine renders its own plugin from the registrations that apply to it, so a node-scoped skill sits +in the same `mesh` plugin as a mesh-scoped one, on that machine only. The home scope places an item +where the person's own items live, without the plugin's prefix, as if written there by hand. The +difference is that the mesh knows it placed the item and can change or remove it. + +**Instructions follow the same scopes.** The agent reads the managed instruction file first, then the +home's instruction file and its rule files, then the project's. These are concatenated, not overridden: +a later file does not cancel an earlier one, which is how the contradiction measured in +[01](01-what-is-configured-today.md) came about. + +- **The mesh's piece** sits in the managed instruction file and is the same on every machine: how a + session on this mesh works, and the conventions. +- **The node's piece** sits in the same file, rendered per machine: its role, and instruction sections + registered for it. +- **Further customisation per machine** sits in the home: a rule file the module places, at the home + scope, beside whatever the person writes there by hand. + +**What the home scope needs from [ADR 0182](../../02-DECISIONS/0182-inside-a-home-the-mesh-owns-what-it-places-and-holds-the-rest-as-found.md).** +That ADR already lets the mesh own what it places in a home and hold the rest as found. So the module +owns each home item it placed, path by path, recorded in its state. It never writes, renames or +removes an item it did not place. A home item with the same name as one the person made is refused +at registration, never overwritten. + ## Where each kind of item goes [02](02-what-the-vendor-allows.md) puts a hard limit on the plugin: it carries skills, subagents, commands, @@ -84,20 +118,20 @@ module's code: It is loaded in place, so a change takes effect at the next session, or at `/reload-plugins` in a running one. Nothing is copied into the home. -## What the module does about the homes +## What the module does about what it did not place -[01](01-what-is-configured-today.md) found stale predecessor files on every machine. Under -[ADR 0182](../../02-DECISIONS/0182-inside-a-home-the-mesh-owns-what-it-places-and-holds-the-rest-as-found.md) -the mesh never writes inside a home except what it owns. So the module can: +[01](01-what-is-configured-today.md) found stale predecessor files on every machine. The module did not +place those, so they are held as found (ADR 0182). It can: -- **report** what it finds: a status tool listing the home's skills, subagents, commands and rule files, - and naming those that duplicate a mesh item or name tools no longer served; -- **import** on request: `claude_code__import` takes an item from one machine's home and registers - it, so a skill written by hand on one workstation becomes the mesh's in one call. Removing the home - copy stays the person's act. +- **report** them: a status tool lists the home's skills, subagents, commands and rule files, says which + the mesh placed, and names those that duplicate a mesh item or call tools no longer served; +- **import** one on request: `claude_code__import` takes an item from one machine's home and + registers it at a scope the operator chooses. A skill written by hand on one workstation becomes a + mesh, node or home item in one call. Removing the original stays the person's act. -`strictPluginOnlyCustomization` would make the homes' items stop loading altogether. That is the -operator's choice to make through the managed settings, not a default of the module. +`strictPluginOnlyCustomization` would make home items stop loading altogether, and home-scoped items +with them. That is the operator's choice to make through the managed settings, not a default of the +module. ## What to confirm first, on one workstation @@ -110,6 +144,7 @@ operator's choice to make through the managed settings, not a default of the mod as documented. 5. `autoMode` in the managed settings changes what the agent refuses (ADR 0213's open point). 6. The account can read the marketplace in the managed directory, which root owns. +7. The managed instruction file and a home rule file the module placed are both loaded, in that order. ## Questions a decision has to answer @@ -118,5 +153,7 @@ operator's choice to make through the managed settings, not a default of the mod - Whether the managed settings are set through tools writing the module's state, or through the controller's settings layer as ADR 0213 has it. If both, which one wins on the same key. - Whether the agent module holds a seat, so that other modules can contribute to it. -- Whether the module may say anything about a home beyond reporting, for example a switch the operator - sets to make home items stop loading. +- The three scopes, and the home scope's ownership rule: the module owns exactly the home paths it + placed, recorded in its state, and refuses a name the person already uses. +- Whether settings take the same three scopes. The home's settings file is the person's own, so it is + left out unless the operator chooses otherwise.