Other tools' files are onboarded through one writer that reaches only the workspace's .troupe/ and the person's config directory, judged by real path, and every file it writes records where it came from, so troupe instructions check can say when that source changes¶
Decision 823 · accepted · 2026-10-09 · issue #516
516 decided that other tools' configuration stops being read at runtime and is onboarded¶
once into Troupe's own files. The maintainer decided for this chunk that the writer is a
dedicated tool confined to .troupe/ and the config directory, as remember is (Decision
649), not write_file behind an approval, which would hand the model a free path
argument.
- One writer, two roots, Troupe's kinds of file.
Troupe.Onboard.write/3is the only thing that writes an onboarded file, for the command line and the tool alike. A file is:repo, under the workspace's.troupe/, or:user, under the person's config directory, and only of a kind Troupe reads there:agents/<name>.md,commands/<name>.md,skills/<name>/...,workflows/<name>.json,mcp.json, and for:userthe person's ownAGENTS.md. Notconfig.yamlorconfig.local.yaml, which have their writer (Decision 686) and hold the keys that decide what may run; notcredentials.json, the brief oronboarded.json. A list of what may be written, not of what may not: a file added to the config directory later is not writable by default. A path with.., an empty or.part, a backslash, a leading/,~or drive letter, or a character a file name cannot have everywhere is refused before anything is read. - Judged where it really is. The file is resolved with
Troupe.Workspace.real_path/1, links and junctions followed, and must be under the workspace's real path joined with.troupe, or under the config directory's real path: a.troupethat is a link, to anywhere, anagentsin it that links out of.troupe/(even into the workspace), or a file that is a link out, is refused with a sentence naming where it resolves. This is Decision 798's edge for reading the brief and #512's rule, applied to what Troupe writes; the readers' half of #512 is its own issue. The file is written at the real path it was judged by, to a temporary file beside it renamed over it, inside a VM-wide transaction on that path. - A repository's file into the repository, the person's own into their config. A
:repoproposal's source is relative to the workspace and really inside it; a:userone starts~/and is really inside the home directory. One never crosses into the other, so a clone cannot write the config directory every session reads, and the person's files never land in a repository (#516's mapping table). The tool also refusestarget: userto an agent defined by the workspace (.troupe/agents/), whatever permission that agent's file gives itself (#511), and refuses on a pod (a session with a bundle), where the bundle's files are the ones that count. - Provenance: frontmatter for Markdown,
onboarded.jsonfor the rest. Every file written recordsimported_from(the source as the proposal names it),imported_hash(the lowercase hex sha256 of the source's bytes) andimported_at(UTC, to the second). In a Markdown file they are three keys at the end of its YAML frontmatter, quoted, any older ones replaced, a frontmatter added when there was none: agents, commands and skills are read as frontmatter and body, and their parsers ignore keys they do not know, so the keys cost nothing and travel with the file into a commit. Any other file, and a rootAGENTS.md, which the loader reads whole into the prompt, records them in a sidecaronboarded.jsonat its root ({"version": 1, "files": {"<path>": {...}}}, sorted by path), not a reserved key: one rule for JSON, YAML and whatever comes next, andmcp.json's own reader is left as it is. The sidecar is written after the file, so a failure between the two leaves a file with no record, proposed again and never taken for unchanged. Not chosen: a key inside each JSON file (a different rule per format, and a keyTroupe.MCP.Localwould have to learn to ignore), and a sidecar for Markdown too (two places to read one fact). - More than one file behind one written. A proposal may carry
also_from, a list of%{source, source_hash}for the other files its content was made from (a Claude Code agent's permissions come from.claude/settings.jsontoo; an opencode agent takes the top-levelpermission; an inlined{file:}), each held to the same edge assource. They are recorded asimported_also, a list of{"from", "hash"}in path order (one line of JSON in a frontmatter, which YAML reads as it is; a list inonboarded.json), absent when there are none. A file is unchanged only when its source and every one of these are, a decline is remembered for all of them, and a change to any is a new proposal and a drift finding of its own ("imported with.claude/settings.json, which has changed since") on theimported_alsoline. - What a source passed over. A source may export
skipped/2, optional, naming each of the other tool's files it found and proposed nothing for, with the reason (linked out of the workspace, disabled, a name Troupe cannot take, a shadowed command);plan/2passes them on asskippedandtroupe onboardlists them first, so a file the person expected is never missing without a word. They change no exit status: the source chose them. - The hash is taken, not trusted. A proposal carries its source's hash, and the writer reads the source again and refuses one that does not match; the tool computes it itself and never takes one from the model. A source that is gone, a directory, or outside where it may be is refused with a sentence.
- Nothing silent.
Troupe.Onboard.plan/2asks the registered sources and passes over a proposal whose file already records the same source and the same hash: the source has not changed since it was onboarded, so the person's own later edits to Troupe's file stand, which is what makes "a second run with nothing changed proposes nothing" true. Everything else is offered with a line diff against what the file holds (all+for a new one): a changed source, or a file onboarding did not write, which is never taken over without a yes.accept/3writes exactly what was shown (the sameimported_at) and refuses when the file changed after it was shown. A no isdecline/2: the source and its hash are remembered in the state directory (<state>/onboard.json, keyed by the file's real path), never in either root, and the proposal is not offered again until its source changes;--alloffers it anyway. So a declined proposal leaves nothing where it would have gone, not even a directory, and the next run does not ask again. - Sources are modules, registered in one line.
Troupe.Onboard.Sourceis@callback proposals(workspace, opts) :: [proposal], a proposal the plain map%{target, path, content, source, source_hash, notes}the chunk fixed between this slice and the next (and the optionalalso_from),optscarryinghome;skipped/2is the optional second callback. A source only proposes; the writer checks, shows, writes and records.Troupe.Onboard.sources/0is@sourcesinTroupe.Onboard, empty in this slice, which #516's slice 4 fills with its agents and commands source; the:onboard_sourcesapplication setting replaces it for a test, or for a script driving a build, and no config file reaches it. A source that raises, or answers something that is not a list of maps, is a refusal naming it, and the other sources are still asked. - The tool:
onboard_write, asks, named only. The librarian's way to write the same files from a session:target(repooruser),path(relative to the root),sourceandcontent; it calls the same writer and logs anonboardedevent (target,path,file,source,source_hash,action) in the session's log. Its default is:ask, unlikeremember:rememberreaches one file of notes, this one writes what decides what runs (an agent's tools and permissions, a command's prompt, an MCP server), so the person sees each file in the approval. Into.troupe/it follows the ordinary rule, soauto_approveor a profile'sautolets it through. - Into the config directory, always asked. A
target: usercall is asked about whateverauto_approve(--auto-approve), a standingallow_sessionor the profile'spermissionssay, the way a refusal is unconditional; only a profile'sdeny(orapprovals: deny, nobody to ask) answers it without a person. The config directory is read by every session on the machine, and what lands there runs without a trust question: a user-layermcp.jsonserver starts unasked and a user agent is everyone's (Decision 700), unlike a workspace's, which is asked about or gated by trust. So a write there must never be unasked. The tool says so through the optionalTroupe.Toolcallbackmust_ask?/1;Troupe.Tools.run_task/4turns that into an approval request withalways: true, whichTroupe.Session.Approvalsanswers only with a person's decision (turningauto_approveon mid-wait does not release it either). A workspace's agent namingonboard_write: autofor.troupe/is the run-time trust gate's (#511, Decision 825), not this decision's. - Named only. It is offered only to a profile that names it (
@named_onlyinTroupe.Tools): the librarian does;buildand every other agent withtools: allis neither offered it nor let call it, which also keeps its spec out of every build prompt. Its refusals are the writer's sentences, plus the two above (a pod, a workspace's agent writing the config directory). troupe onboard [--workspace DIR] [--yes] [--json] [--all]runs in the TUI's VM, astroupe instructions checkdoes (Decision 810): it reads and writes files on this machine and needs no daemon, andTroupe.Onboardjoins the harness modulesmix troupe.xreflets the TUI call, so the decisions are the harness's and the TUI only asks. Each file is printed as its name, its status and source, the source's notes and the diff, thenWrite <file>? [y/N], at a terminal only, read astroupe bench --livereads its question (TUI Decision 141). With nobody to ask it prints every proposal, writes and remembers nothing, and exits 2.--yeswrites them all;--jsonprints them (proposalswithtarget,path,file,source,source_hash,status,notes,diff;refused;unchanged;declined) and writes nothing unless--yestoo. Exit 1 for a refusal or a failed write. A workspace that is not a directory here is refused with 2: onboarding writes a local workspace, never a pod's.- Drift is read from the records, not found by a search.
troupe instructions check(Decision 810) gains a fifth kind,drift:Troupe.Onboard.drift/2reads the provenance back, from the frontmatter of the Markdown files inagents/,commands/andskills/under each root (links not followed) and from each root'sonboarded.json, hashes each recorded source and reports, on the line ofimported_hash(1 for the sidecar's files), one that has changed ("troupe onboardshows what changed") or is gone. The instruction files are still the loader's alone, as 810 says; a record that names a source where none may be (a repository's file pointing outside the workspace) is passed over rather than read, so a repository cannot use the check to ask whether a file elsewhere on the machine has a given content.--jsonaddsonboarded(file,path,imported_from), and the count line names the onboarded files when there are any.
Governs: apps/troupe_core/lib/troupe/onboard.ex, apps/troupe_core/lib/troupe/onboard/source.ex, apps/troupe_core/lib/troupe/tools/onboard_write.ex