A session's start asks about onboarding first and starts the librarian only once that is answered, over onboard.plan, onboard.apply, onboard.decline and memory.decline; the librarian writes the brief only¶
Decision 835 · accepted · 2026-10-10 · issue #516 · supersedes 827
Issue #516, the chunk's third wave, as the maintainer decided it: at a session's start,
first onboarding, then the librarian. Amends Decision 827 in three places (its
supersedes is that part): the librarian no longer onboards, the notice is said at every
start while something is due rather than once per version, and a start now asks rather
than only telling the person to run troupe onboard.
- What is due, decided in one place.
Troupe.Onboard.Notice.onboarding/2:firstwhen the workspace has other tools' files, nothing is onboarded and nothing declined there (827's test, the plan it took to decide kept);outdatedwhen the workspace's recorded onboarding version (Troupe.Onboard.onboarded_version/2) is older thanTroupe.Onboard.version/0;noneotherwise, on a pod or a worker's machine, and once the person said no under this version. Only in a git repository (a.githere or above, asTroupe.Instructions.repository_root/1finds it): a start in a directory in none isnonebefore any source is asked. In the home directory, Claude Code's own~/.claude/looked like a workspace's.claude/, so a start there planned by walking the whole home tree and proposed~/AGENTS.md, and with the notice said at every start it would have done so every time.Troupe.Onboard.Notice.brief/2:firstandstaleasrefresh_duehas them (Decisions 649, 696, 713, the TUI's 127),outdatedwhen an older survey wrote the brief (Troupe.Memory.survey_version/0) and the person has not said no to that,noneotherwise or with memory off. The event and the protocol read the same functions, so they cannot disagree. - The answers are the person's, in the state directory.
<state>/onboard.jsongainsonboarding_declined(the workspace's real path to the rules' version the person said no under) andbrief_declined(the brief's path, so every checkout of a repository shares it, to the survey's version), besidedeclined, the per-file nostroupe onboardalready kept (Decision 823). A no lasts until the version changes; nothing is written into the repository by saying no. - The notice repeats until answered.
onboarding_suggestedis logged at every start while onboarding is due or the brief outdated and not declined for that version, withdue,brief_dueandcounts(files,write,create_agents_md: the workspace's files a client would ask about) added to what 827 gave it. 827 said it once per workspace and version and remembered that it had (suggested): a person who closed the client before answering was never asked again, and a client that asks on the event (the desktop app) would never ask. The notice now writes nothing at all. The cost is the first-time plan at each start of a workspace that has other tools' files and has not answered, which a workspace with none never pays (found?/1first, as 827 has it). - The protocol (additive to v1).
onboard.plan {workspace}answersonboarding(due,recorded,version,tools,items,skipped),brief(due,recorded,version) andrefusal(Troupe.Onboard.Pod's sentence on a worker's machine, where onboarding is never due). Items are listed only while onboarding is due, and then every one the person would see: the workspace's and their own (Troupe.Onboard.plan/2for every target, every registered source); while it is not, no source is asked, so a start with nothing due does not walk the workspace. Each item carriesid,target,path,shown,status,question(writeorcreate_agents_md),source,also_from,was,notesanddiff, which is whattroupe onboardshows.toolsnames the other tools by their files (Troupe.Onboard.Start.tool/1), andskippedholds what the sources passed over and any proposal the writer would refuse.onboard.apply {workspace, ids | all}writes the items named, or everywriteone (a newAGENTS.mdonly by its id: Decision 827's own question), answeringwrittenandrefused;onboard.decline {workspace, ids | all}says no to them,allalso remembering the no for this version.memory.decline {workspace}remembers a no to an outdated brief; the contract's placeholder name is the method's.command_idis optional on all three and makes a retry a no-op. The daemon's alone,method_not_foundon a worker. - An id is what was shown. A 16-character hash of the target, the path, the source and
each other file it is made from with their hashes, and what the file holds now. Apply
and decline plan again and act by id, so a file whose source or content changed since
the person saw it names nothing and is refused with a sentence, never written over what
was not shown. Not chosen:
target:pathas the id (a changed source would be written under a yes given to the old one). - Answered is stamped. A call that answers every item its plan held records the
workspace as onboarded under this build's rules (
Troupe.Onboard.stamp/1), astroupe onboarddoes after a run that left nothing unanswered (827). A yes to all that leaves a newAGENTS.mdto its own question is not answered yet; the question's answer is. - Scopes.
onboard.planandonboard.applytakeadmin, whatconfig.setandmemory.forgettake: the plan answers with what other tools' files hold at the path it is given, the person's own (~/.claude/CLAUDE.md, their config directory's) among them, so acontroltoken would read files under the person's home; a yes writes into the repository and into the person's config directory.onboard.declineandmemory.declinetakecontrol: they write only the person's own answer. The local clients hold all three: a Unix socket's connection, and a loopback TCP or WebSocket one with the discovery file's token (the terminal UI's link and the desktop app's), are givenobserve,controlandadmin. - The librarian writes the brief only.
priv/agents/librarian.mdloses 827's onboarding pass andonboard_writefrom its tools; it starts fromREADME.md, reads what onboarding wrote (already in its prompt asAGENTS.mdand.troupe/rules/), and keeps out of the brief what the person did not let in.onboard_writestays a named-only tool (Decision 823) for a profile that names it. The survey's version stays 1: for the same repository, onboarded or not, the brief it writes does not change; the onboarding was a step before it, now taken before it starts. - The order is the client's, because starting a session is (649). The daemon says what
is due; a client asks about onboarding and starts the librarian only once onboarding is
answered, so it reads the onboarded
AGENTS.md. The terminal UI's flow is TUI Decision 154 (clients/tui/lib/troupe/client/daemon/start.ex); the desktop app's is its own. - The desktop app's flow (
@troupe/client'sStartQuestions,views/Onboard.tsx; #544, #550). The questions sit where the approval panel sits, not in a modal, the default (Onboard, Re-run) first and filled, and nothing takes the focus from the composer. Review is offered beside Re-run for an out-of-date onboarding too, since a re-run can replace files and the diff costs nothing to show. A newAGENTS.mdis asked in its place in the plan under Review, or after the rest is written under Onboard, in 827's words with its diff. The client keeps the first plan's items for the follow-up questions, because after the first write the plan answers nothing due. Every replay asks for the plan again and the plan decides, so a session opened after it was answered asks nothing; the harness's own line stays in the transcript for an older daemon, a replay or a team session. A team session runs no flow and asks the local daemon nothing, and a plan's refusal shows its sentence and asks nothing. The librarian starts only for a session this app just started (the first run's session counts), after onboarding is answered, on the same conditions as the terminal UI's (memory on, a git repository, a model,memory_auto_refreshfor the automatic start); the outdated brief's Re-run sits behind the same conditions.
Governs: apps/troupe_core/lib/troupe/onboard/notice.ex, apps/troupe_core/lib/troupe/onboard/start.ex, apps/troupe_gateway/lib/troupe/gateway/dispatch.ex, apps/troupe_protocol/lib/troupe/protocol/schema.ex, clients/tui/lib/troupe/client/daemon/start.ex, clients/gui/packages/client/src/onboard.ts, clients/gui/apps/desktop/src/views/Onboard.tsx