manor AGENTS.md

Local Development

• Use the Docker workflow by default.
• Use ./manor-start for install and lifecycle commands. Do not use raw Compose for normal starts or restarts.
• Before starting or restarting Manor, check whether the gitignored manor-start.local exists and is executable. The official launcher runs it first so machine-local environment and secret injection are preserved.
• Keep machine-specific startup behavior in manor-start.local, based on manor-start.local.example. Never add secrets or personal environment values to the committed launcher.
• For Butler UI work, run ./manor-start start --dev so the Butler container has source mounts, BUTLER_HOT_RELOAD=1, and Vite middleware enabled.
• Before relying on hot reload, confirm the running Butler container reports hot reload mode. If it is in static mode, run ./manor-start restart --dev.
• On Docker Desktop, if UI edits do not appear, prefer enabling polling for the dev server watcher before doing a full image rebuild.
• Manor self-improvement uses the active checkout. Do not create a branch, worktree, or commit unless the operator explicitly asks.
• Leave experiments uncommitted. A source restart builds the working tree; if startup fails, Manor retries from clean HEAD without resetting or cleaning the user's files.

Agent Judgment And Hard Boundaries

• Give Butler and Worker the goal, relevant context, live capabilities, constraints, and useful evidence. Let the agents choose and revise the execution path.
• Keep workflow prompts focused on outcomes. Prescribe an exact sequence only when the operator asked for that method or the sequence protects a real safety or integrity boundary.
• Use deterministic enforcement for authentication, permissions, Content Admission Review, operator approval, package integrity, ownership, concurrency, destructive actions, and proof binding.
• Treat a missing capability in one agent environment as a routing fact. Infer whether Butler should advise, prepare, inspect, or execute, and whether Worker should perform the environment-dependent work.
• Keep tool contracts goal-oriented where judgment helps. Return concrete runtime facts and results so the agent can adapt without encoding every reasonable branch in server code.
• Test outcomes and invariants. Allow multiple valid execution paths when the safety boundary and required evidence stay intact.
• Add tests only when they materially improve confidence in important behavior or protect against a demonstrated regression.
• Scope the Butler-Worker turn budget to one operator turn. Start a fresh allowance when each queued operator message begins. Count one turn only when Butler successfully dispatches Worker work that will enter adversarial review: Butler -> Worker -> Review. Rework dispatched after a rejection consumes the next turn. Worker tool calls and internal turns, review attempts or schema retries, callback registration, held context, and startup recovery do not consume turns.
• Treat the turn budget as an execution boundary. Autonomous supervision must not delete, detach, hand off, or replace a Worker to obtain a fresh allowance. A new operator turn resets usage, while the configured limit remains unchanged.
• Scope every terminal Butler reply to the latest operator message that caused the Worker dispatch. Carry Butler-side checks and the subsequent Worker report into review, lead with the direct answer, and do not recap accepted earlier work unless it is relevant. Automatically replace a completed review scope for new follow-up work; keep incomplete or rejected scope visible and governing until Butler explicitly replaces it.
• Ask the operator when a missing choice would materially change the result. Handle ordinary routing, command selection, retries, and verification choices through agent judgment.