docs: correct and expand the .tembo.json hooks reference

[tembo]

Documentation-only update to features/hooks.mdx, verified line-by-line against apps/api/src/agent/sandbox/temboConfig.ts and every one of its call sites.

⚠️ Please confirm: prePush is documented but never runs

The most significant finding. features/hooks.mdx currently tells users:

prePush - Runs after Tembo makes changes, before pushing and opening a PR.

That does not happen in the current code:

• prePush is still accepted and validated by TemboConfigSchema (temboConfig.ts:15).
• The only two runHook('prePush', ...) call sites are commented out — solve_issue/index.ts:742 and feedback_loop/index.ts:771.
• Both of those tasks are now disabled stubs that throw "<task> task is disabled" (~95% of each file is commented out).
• The live task, agent_run, only calls runHook('setupScript') (agent_run/index.ts:404). prepare.ts:269 likewise runs only setupScript.
• Nothing in packages/agent-runtime runs hooks at all.

So a user who puts lint/test commands in prePush believes pushes are gated when they are not. I documented the actual behavior with a warning and removed prePush from the main example so we are not shipping a non-functional sample. If this is a temporary disablement with a fix landing soon, say so and I will reword to "temporarily disabled" instead.

Other corrections and additions

Behavior	Source
setupScript is skipped when a session restores an existing workspace	agent_run/index.ts:402, sandboxTask.ts:216-229
setupScript also runs during snapshot builds	qemu/prepare.ts:268
Hooks run inside the tembo.nix dev shell; pre-baked golden deps use a saved PATH instead	temboConfig.ts:81-135
postClone is a legacy alias for setupScript, and setupScript wins when both are set	temboConfig.ts:11-20, tests/sandbox/temboFlake.test.ts:96-122
Invalid .tembo.json falls back to defaults and continues silently	temboConfig.ts:72-78
Unknown keys are ignored (non-strict Zod), so setupScripts is dropped without error	temboConfig.ts:25-30
Hook command output streams to the build log only during snapshot builds	prepare.ts:270-277 (no onCommandLog in agent_run)

Docs added/updated

• features/hooks.mdx — rewritten as an accurate reference: when setupScript runs and when it is skipped, tembo.nix interaction, failure semantics (non-zero exit logs and continues), and a config reference table.
• features/snapshots.mdx — one <Note> distinguishing the Settings-configured snapshot setup script from the .tembo.json setupScript hook.

Key knowledge gaps addressed

1. A silently non-functional hook users may be relying on for push gating.
2. The stale-snapshot pitfall — changing setupScript has no effect on sessions restoring from an existing snapshot until it is rebuilt. This was undocumented and is the most likely "my setup command is not running" support case.
3. Silent failure modes — malformed .tembo.json and typo'd keys both degrade to "no hooks" with nothing surfaced in the session.

No new pages, so docs.json navigation is unchanged. All internal links verified to resolve.

Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

      

---

Note

Low Risk
Documentation-only changes with no runtime, auth, or data-path impact.

Overview
Rewrites the Hooks docs so they match current product behavior instead of implying prePush gates pushes.

prePush is now called out with a warning: it is validated in .tembo.json but not executed; the example no longer shows lint/test in prePush. setupScript is documented for fresh clones and snapshot builds, and explicitly skipped when resuming or restoring from a snapshot, including the need to rebuild snapshots after hook changes.

New sections cover tembo.nix dev-shell behavior, failure handling (non-zero exits log and continue; use && to fail fast), a configuration reference table (postClone alias, silent invalid JSON / ignored keys), and Related links. Snapshots gains a short note separating the Settings setup script from the .tembo.json setupScript hook.

^{Reviewed by Cursor Bugbot for commit 344bd2e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tembo	🟢 Ready	View Preview	Aug 14, 2026, 8:09 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[tembo]

Requesting review from @DarrenBaldwin07 who has experience with the following files modified in this PR:

• features/hooks.mdx
• features/snapshots.mdx