System prompt

Drop a SYSTEM.md in $ZOT_HOME to replace the built-in identity and zot-docs guidance for every run. Per-invocation, --system-prompt still wins; delete the file to revert to the default.

Custom prompts still receive appended instructions and generated context, including AGENTS.md, skills, auto-swarm guidance when enabled, and the date, working directory, and Platform: <goos>/<goarch> footer. On Windows the footer also notes that the bash tool runs cmd.exe, not a POSIX shell. Use --no-context-files to omit AGENTS.md instructions for one run.

Use --append-system-prompt (repeatable) to layer extra instructions on top without blowing the default away.

Extension replacements

Extensions can subscribe to before_agent_start to inspect and replace the complete assembled prompt before the first model call. Unlike SYSTEM.md or --system-prompt, this replacement happens after generated context and appended instructions have been added. The host uses the returned string exactly, including an empty string, without appending anything else.

The result stays stable across ordinary follow-up messages and tool-loop steps. Model/session changes, conversation clears, and explicit prompt rebuilds trigger a new preparation pass from the base prompt. If a reset occurs while an extension is responding, the stale preparation is discarded and retried against the current base.

Subscribed extensions can see and replace every system instruction, including private context-file content. This does not alter tool permissions. See Extensions for the protocol, Go SDK hook, timeout behavior, and size limits.