The handoff

Two files come out of the run, and they do different jobs. Getting them the wrong way round is the usual mistake: one is read on every session start and has to stay short, the other is a one-time script for the first session.

Where the checklist lands depends on the agent, because each reads a one-shot instruction from a different place: Claude Code takes it as a slash command at .claude/commands/chatfuel/finish-setup.md, and Codex takes it as a skill at .agents/skills/chatfuel-finish-setup/SKILL.md. The text is the same; the Codex copy gets a frontmatter block prepended, which is what makes it valid in the second place.

The instructions file

Outside --embed, the wizard writes CLAUDE.md or AGENTS.md outright. It is deliberately short, and holds nothing a later session could work out for itself:

• The module routes this deployment has. A hidden module contributes no route of its own, so it is not in that line.
• The skills to read before touching the API, one per installed module with its description. chatfuel-core is not on the list even though it is always installed; the validator line below is what points at it.
• Which .env keys are secrets, with NEVER print or commit beside them.
• Where the auth module's accounts sign up and which Chatfuel workspace their bots land in, when that module is installed.
• The line that resumes the guided setup.

Whether each skill is named or spelled out as a full path is the agent's business: Claude Code loads its skills directory itself, and Codex is told exactly where to look. That is the same split as in Skills.

In --embed mode it is a marked block

An embed target already has an instructions file, and it belongs to somebody else. So the wizard writes a marked section instead of the file:

<!-- chatfuel:begin -->
<!-- chatfuel:end -->

If the file is missing, the section becomes the file. If the markers are already there, the region between them is rewritten in place and everything around it is left alone. If the file exists without them, the section is appended. Re-running --embed therefore refreshes our half and touches nothing of yours.

The block itself is shorter than the standalone version: the vendored footprint's location, the skills to read, the wiring guide, the secrets line, and the resume line.

The setup checklist

The checklist is a prompt written at your project. It tells the agent what to say in its first message — a short celebration, a three-line tour of the modules that were installed, the deep links to whatever was seeded, and an open floor — in your language, matched from your own messages. Then, without waiting for a reply, it tells the agent to start the dev server itself as a background process, because making you start it by hand is the one thing the run has already earned the right not to do.

Under that come the facts a later session cannot re-derive: which Chatfuel workspace this is pointed at, which skills were installed and in which directory, every module with its deep link, the Chatfuel role permissions each one needs, and the .env keys with the secret ones called out. There is a passage about the two places the app now lives — local and, if you deployed, live — and which one follows your edits, because people change something locally, look at the live URL, and see nothing. It closes with two rules: validate any new GraphQL against the bundled schema with chatfuel-core's validator, and never print the token.

In --embed mode the checklist is a different document: a numbered wiring list — install these dependencies, add the ~ui and ~api aliases, wire the CSS entry, wire the dev proxy, mount the entry components — with the host stack named if the wizard could detect it.

The module guides inside it

Every module but core carries a handoff.md, and the wizard inlines the ones you installed into the checklist verbatim, under a ## Module guides heading — a module with no such file is skipped rather than announced. That is what makes the checklist long and worth keeping: a fragment names its module's routes and deep links, what to read in the skill before changing anything, a numbered list of first tasks, and usually a closing list of the things that look like bugs and are not.

Those first-task lists are where the prompts come from.

Resuming it later

The checklist is a file on disk, so a run that ended without a handoff loses nothing.

The instructions file prints whichever of those applies, and names the checklist's path in the Codex case. When the wizard launches the agent for you, all it types is the same thing: the slash command for Claude Code, and for Codex a sentence telling it to read AGENTS.md and carry out the checklist at that path.