name: monk description: "Deploy and operate applications with Monk through the local monk-agent MCP companion. Use when the user wants to install Monk, sign in, analyze a project, deploy locally or to cloud, inspect workloads, provide secrets securely, or troubleshoot Monk-managed infrastructure. MVP hosts are Claude Code, Codex, and Cursor." allowed-tools: Bash(*), Read, WebFetch, Task, mcp__plugin_monk_monk__monk_agent_clear_state, mcp__plugin_monk_monk__monk_agent_clear_history, mcp__plugin_monk_monk__monk_auth_status, mcp__plugin_monk_monk__monk_auth_logout, mcp__plugin_monk_monk__monk_install_status, mcp__plugin_monk_monk__monk_install_run, mcp__plugin_monk_monk__monk_runtime_status, mcp__plugin_monk_monk__monk_session_init, mcp__plugin_monk_monk__monk_scope_status, mcp__plugin_monk_monk__monk_scope_bind, mcp__plugin_monk_monk__monk_scope_workspace_list, mcp__plugin_monk_monk__monk_scope_workspace_delete, mcp__plugin_monk_monk__monk_scope_project_delete, mcp__plugin_monk_monk__monk_org_usage, mcp__plugin_monk_monk__monk_org_billing_alerts_get, mcp__plugin_monk_monk__monk_org_billing_alerts_set, mcp__plugin_monk_monk__monk_account_status, mcp__plugin_monk_monk__monk_account_select, mcp__plugin_monk_monk__monk_rbac_access, mcp__plugin_monk_monk__monk_rbac_assign, mcp__plugin_monk_monk__monk_rbac_role, mcp__plugin_monk_monk__monk_project_analyze, mcp__plugin_monk_monk__monk_project_configure, mcp__plugin_monk_monk__monk_project_deploy, mcp__plugin_monk_monk__monk_environment_list, mcp__plugin_monk_monk__monk_environment_select, mcp__plugin_monk_monk__monk_environment_delete, mcp__plugin_monk_monk__monk_capsule_setup, mcp__plugin_monk_monk__monk_capsule_list, mcp__plugin_monk_monk__monk_capsule_secrets_update, mcp__plugin_monk_monk__monk_capsule_schedule_get, mcp__plugin_monk_monk__monk_capsule_schedule_update, mcp__plugin_monk_monk__monk_cicd_setup, mcp__plugin_monk_monk__monk_cluster_status, mcp__plugin_monk_monk__monk_cluster_peers, mcp__plugin_monk_monk__monk_cluster_providers, mcp__plugin_monk_monk__monk_cluster_list, mcp__plugin_monk_monk__monk_cluster_create, mcp__plugin_monk_monk__monk_cluster_grow, mcp__plugin_monk_monk__monk_cluster_peer_remove, mcp__plugin_monk_monk__monk_cluster_peer_tag, mcp__plugin_monk_monk__monk_cluster_peer_set_certificate, mcp__plugin_monk_monk__monk_cluster_peer_reset_certificate, mcp__plugin_monk_monk__monk_cluster_upgrade, mcp__plugin_monk_monk__monk_cluster_delete, mcp__plugin_monk_monk__monk_cluster_exit, mcp__plugin_monk_monk__monk_cluster_provider_ensure, mcp__plugin_monk_monk__monk_cluster_price, mcp__plugin_monk_monk__monk_cluster_catalog, mcp__plugin_monk_monk__monk_cluster_estimate, mcp__plugin_monk_monk__monk_cluster_ingress_status, mcp__plugin_monk_monk__monk_cluster_ingress_ensure, mcp__plugin_monk_monk__monk_cluster_ingress_list_certificates, mcp__plugin_monk_monk__monk_cluster_ingress_set_certificate, mcp__plugin_monk_monk__monk_cluster_ingress_reset_certificate, mcp__plugin_monk_monk__monk_cluster_registry_status, mcp__plugin_monk_monk__monk_cluster_registry_ensure, mcp__plugin_monk_monk__monk_cluster_registry_reset, mcp__plugin_monk_monk__monk_cluster_forget, mcp__plugin_monk_monk__monk_cluster_switch, mcp__plugin_monk_monk__monk_cluster_join, mcp__plugin_monk_monk__monk_cluster_bind, mcp__plugin_monk_monk__monk_watcher_status, mcp__plugin_monk_monk__monk_watcher_setup, mcp__plugin_monk_monk__monk_watcher_remove, mcp__plugin_monk_monk__monk_preferences_get, mcp__plugin_monk_monk__monk_preferences_set, mcp__plugin_monk_monk__monk_preferences_delete, mcp__plugin_monk_monk__monk_secret_request, mcp__plugin_monk_monk__monk_secret_list, mcp__plugin_monk_monk__monk_secret_add, mcp__plugin_monk_monk__monk_secret_remove, mcp__plugin_monk_monk__monk_secret_push, mcp__plugin_monk_monk__monk_credentials_request, mcp__plugin_monk_monk__monk_credentials_status, mcp__plugin_monk_monk__monk_credentials_delete, mcp__plugin_monk_monk__monk_workload_status, mcp__plugin_monk_monk__monk_workload_logs, mcp__plugin_monk_monk__monk_workload_stop, mcp__plugin_monk_monk__monk_workload_delete, mcp__plugin_monk_monk__monk_workload_purge, mcp__plugin_monk_monk__monk_workload_unload, mcp__plugin_monk_monk__monk_analyzer_diagnose, mcp__plugin_monk_monk__monk_docs_search, mcp__plugin_monk_monk__monk_package_list, mcp__plugin_monk_monk__monk_package_search, mcp__plugin_monk_monk__monk_package_info, mcp__plugin_monk_monk__monk_package_dump, mcp__plugin_monk_monk__monk_dump, mcp__plugin_monk_monk__monk_arrowscript_operator_groups, mcp__plugin_monk_monk__monk_arrowscript_operator_list, mcp__plugin_monk_monk__monk_arrowscript_operator_search, mcp__plugin_monk_monk__monk_arrowscript_operator_doc, mcp__plugin_monk_monk__monk_feedback_submit, mcp__plugin_monk_monk__monk_action_status

Using Monk

Model

Monk is operated through a local companion named monk-agent. The companion exposes MCP tools and a localhost dashboard, then talks to local monkd through the @monk-io/monk TypeScript client from monk-ts2.

Target hosts for the MVP are Claude Code, Codex, and Cursor. Other Agent Skills clients are best-effort until tested.

Preflight

Before deploying:

Confirm the local Monk MCP tools/resources are available AND authenticated. In the MVP these are backed by monk-agent. The Monk MCP server challenges for authentication on connect, so until the user signs in the host has no valid token and the monk.* tools will be ABSENT from your tool list (the host drops an unauthenticated server's tools). This is the normal state on a fresh install — it is an AUTH state, NOT a "server is down" state. The SessionStart hook injects an explicit note when the agent is running but signed out; trust it.
- If a SessionStart note says the agent is running but you are NOT signed in, OR the monk.* tools are absent right after install: the user needs to SIGN IN. Tell them to sign in, then wait. Do NOT describe this as a connection or restart problem, and do NOT keep probing to diagnose it.
- If the tools were present and working earlier this session and a monk.* call now fails with a connection/transport error: the MCP connection went stale. Plugin updates restart monk-agent, so this is expected right after an update — tell the user to reconnect, then wait. Either way the fix is the host MCP flow — do not delegate to subagents, inspect MCP config files, or retry in a loop; one signal is the answer. How to sign in / reconnect — always the host MCP auth flow (there is no in-band sign-in tool; the host flow also establishes the agent's Monk session):
- Claude Code: run /mcp and authenticate the monk server (this both reconnects and signs in).
- Codex CLI: codex mcp login monk.
- Cursor: the MCP login flow for the monk server. A 401/Unauthorized on a monk.* call that worked earlier this session means the host's MCP token lapsed — re-run the host auth flow above; it is NOT a reason to look for an in-band auth tool. Never work around an unready Monk by shelling out to monk/monkd, Docker, or another hosting platform, and never propose a non-Monk deploy target: get Monk signed in / connected and continue. To file a bug, feature, or integration request, use monk.feedback.submit once signed in (it reaches the Monk team directly). If you cannot sign in at all, the local dashboard's feedback form still works.
If they are missing, use the installer workflow. Host install hooks should run scripts/start-monk-agent.sh on macOS/Linux or scripts/start-monk-agent.ps1 on Windows so the local MCP server is installed and started. Do not fall back to direct monk CLI operations.
Workspace binding. monk-agent learns the active workspace from the MCP roots capability when the host advertises it (Claude Code does; capability-aware Codex/Cursor builds do too). When roots are present, no explicit setup is required and you should not call monk.session.init defensively. Call monk.session.init only when:
- the host did not advertise the roots capability during initialize, or
- you need to override the picked root with a specific absolute path, or
- you want to record host/client/plugin-version metadata for telemetry. When you do call it, pass the absolute project directory as workspaceRoot and include pluginVersion: "0.1.53" so telemetry reports the real plugin version. monk-agent never falls back to its own working directory.
Confirm auth status with monk.auth.status (once the tools are available). If signed out, the agent signs in through the host MCP auth flow from step 1 — that flow also establishes the upstream Monk session, so there is no separate tool to start auth. Switching Monk accounts. monk.auth.status reports the Monk user identity monk-agent itself is signed in to (an email), which is what every Monk operation is attributed to. Two different things get called "account" — do not conflate them, and ask which the user means if it is ambiguous:
- a different Monk USER (different email) → monk.auth.logout, below;
- personal vs org context WITHIN that user → monk.account.select, which does not change who the user is signed in as. The host-side logout (/mcp disconnect, codex mcp logout monk) clears only that host's credentials for the MCP server — monk-agent stays signed in, so signing back in reuses the SAME Monk user without asking. To change identity: call monk.auth.logout (they approve in the dashboard, or they can use the dashboard's own Log out button), then re-run the host auth flow from step 1 — that time they are asked which account to use, and can also create a new one. Warn them that the host may still LIST the monk server as authenticated afterwards, because it holds a token the agent has just revoked; they should explicitly choose reconnect/re-authenticate instead of trusting that state. Logging out keeps stored secrets, credentials, and history, so never suggest monk.agent.clear_state to change accounts.
Confirm runtime status. monk-agent requires Monk CLI and monkd locally. If missing or broken, use monk.install.status to inspect the platform-specific humanExplanation, relationships, components, checks, probes, troubleshootingHints, nextAction, and actions. Explain the current platform's install graph before running remediation. monk.install.run is dry by default: without execute: true it only inspects status and runs nothing. Use execute: true to run remediation. Installation, upgrade, and repair actions also require approved: true after explicit user or dashboard approval.

Tooling contract

Prefer monk-agent MCP tools and resources:

monk.agent.clear_state (only when the user explicitly asks to clear local Monk Agent state)
monk.agent.clear_history (tidy completed dashboard tasks and resolved approvals; leaves live work and credentials intact)
monk.auth.status
monk.auth.logout (to sign out of Monk, or to sign in as a DIFFERENT Monk user — not for personal/org switching within the same account, which is monk.account.select)
monk.install.status
monk.install.run
monk.runtime.status
monk.session.init
monk.scope.status
monk.scope.bind
monk.scope.workspace_list
monk.scope.workspace_delete
monk.scope.project_delete
monk.org.usage
monk.org.billing_alerts.get
monk.org.billing_alerts.set
monk.account.status
monk.account.select
monk.rbac.access
monk.rbac.assign
monk.rbac.role
monk.project.analyze
monk.project.configure
monk.project.deploy
monk.environment.list
monk.environment.select
monk.environment.delete
monk.capsule.setup
monk.capsule.list
monk.capsule.secrets.update
monk.capsule.schedule.get
monk.capsule.schedule.update
monk.cicd.setup
monk.cluster.status
monk.cluster.peers
monk.cluster.providers
monk.cluster.list
monk.cluster.create
monk.cluster.grow
monk.cluster.peer.remove
monk.cluster.peer.tag
monk.cluster.peer.set_certificate
monk.cluster.peer.reset_certificate
monk.cluster.upgrade
monk.cluster.delete
monk.cluster.exit
monk.cluster.provider.ensure
monk.cluster.price
monk.cluster.catalog
monk.cluster.estimate
monk.cluster.ingress.status
monk.cluster.ingress.ensure
monk.cluster.ingress.list_certificates
monk.cluster.ingress.set_certificate
monk.cluster.ingress.reset_certificate
monk.cluster.registry.status
monk.cluster.registry.ensure
monk.cluster.registry.reset
monk.cluster.forget
monk.cluster.switch
monk.cluster.join (portable saved-cluster store not implemented yet)
monk.cluster.bind
monk.watcher.status
monk.watcher.setup
monk.watcher.remove
monk.preferences.get
monk.preferences.set
monk.preferences.delete
monk.secret.request
monk.secret.list
monk.secret.add
monk.secret.remove
monk.secret.push
monk.credentials.request
monk.credentials.status
monk.credentials.delete
monk.workload.status
monk.workload.logs
monk.workload.stop
monk.workload.delete
monk.workload.purge
monk.workload.unload
monk.analyzer.diagnose
monk.docs.search
monk.package.list
monk.package.search
monk.package.info
monk.package.dump
monk.dump (compatibility alias for package/template dump)
monk.arrowscript.operator.groups
monk.arrowscript.operator.list
monk.arrowscript.operator.search
monk.arrowscript.operator.doc
monk.feedback.submit
monk.action.status
monk://agent/status
monk://workspace/manifest
monk://workspace/workloads
monk://workspace/deploys
monk://workspace/clusters
monk://workspace/cluster-context
monk://workspace/scope
monk://workspace/feed
monk://workspace/events
monk://workspace/secrets
monk://workspace/diagnostics
monk://account/scopes

If the host has not exposed these exact names yet, use the available Monk MCP tooling only if it is backed by Monk or monk-agent. Do not operate live Monk-managed infrastructure through shell commands.

On hosts that expose ReadMcpResourceTool/ListMcpResourcesTool (Claude Code), the server name for any monk://... resource below is not simply monk — Claude Code namespaces plugin-supplied MCP servers, so a bare monk is rejected with "Server not found". If that happens, the error lists the available server names; pick the one starting with plugin: that also contains monk (that combination identifies this plugin's own server, not an unrelated MCP server that happens to have "monk" in its name) and retry with that instead of asking the user for help.

Use monk://workspace/feed as the durable task and prompt ledger for the bound workspace. Read it after host-side MCP timeouts, interrupted approval flows, agent restarts, or uncertainty about whether a long-running operation is still pending, approved, failed, or completed. It contains durable action and request items with dashboard URLs; inspect it before retrying approval-backed or cost-bearing operations so repeated calls do not create duplicate work.

When an action fails, read the error details from monk://workspace/feed and quote them in chat — do not ask the user to fetch error text from the dashboard. Dashboard URLs returned by tools (/?item= or /?action=) are deep links: share them as-is when pointing the user at an approval or a running action; if the user already has the dashboard open, their existing tab reveals the linked item automatically.

Use monk://workspace/cluster-context to know the current execution target. Cluster targeting is logical per workspace/session: mode: "local" means tools and Monk RPC use the local daemon, while mode: "cluster" means they target the selected saved cluster through monkcode. monk.cluster.create automatically selects the newly created cluster on success and says so in its result. Use monk.cluster.switch to select another saved cluster, monk://workspace/clusters or monk.cluster.list to inspect available choices, and monk.cluster.exit to clear selection and return to local mode without deleting cloud infrastructure.

Scope: owner, project, environment

Cluster and platform operations run inside a Monk scope: an owner (the user's personal account or an org), an optional project, and an optional environment. A workspace must be bound to one owner/project before scope-gated cluster operations (create, grow, peer changes, registry, switch, delete) will run.

Check scope with monk.scope.status (or read monk://workspace/scope) before cluster work, and resolve these states first:
- missing_workspace: call monk.session.init with the absolute workspace root.
- not_bootstrapped: the Monk account is not initialized on the platform yet; finish auth/onboarding.
- unbound: bind the workspace with monk.scope.bind. If more than one owner scope is available (personal + orgs), list the options and ask the user which one to use — never pick an organization on the user's behalf. Pass confirmedByUser: true only after they chose.
- ambiguous: the workspace is linked in more than one owner/project; rebind to one canonical scope with monk.scope.bind and confirmMove: true.
- resolved: proceed.
List available owners and projects from monk://account/scopes. Bind with monk.scope.bind: ownerKind: "personal", or ownerKind: "org" with orgSlug; optionally projectSlug, createProject: true to create a missing project, and confirmMove: true to move an already-bound workspace. Do not move a bound workspace to a different owner/project without the user's intent. A first-time bind on a multi-scope account is rejected unless confirmedByUser: true — that flag asserts the user explicitly chose the owner scope in conversation, so always ask before passing it.
Select a deployment environment with monk.environment.list and monk.environment.select. A resolved environment determines the default cluster and the monk.project.deploy target, so once scope and environment are set, deploy needs no manual monk.cluster.switch.
Personal scope is not RBAC-gated. Org scope enforces the organization's cluster create/manage/delete policy; a permission denial is definitive, so surface it and, if appropriate, have the user request access rather than retrying blindly.
Scope tolerates brief control-plane outages: monk.scope.status may report stale: true (served from cache) with pendingPlatformOps > 0 (platform writes queued for retry). Keep working; queued writes flush when the control plane returns. An auth error ("not signed in" or token rejected) is NOT transient — re-authenticate through the host MCP auth flow (see Preflight) before retrying.

Safety rules

Approvals are owned by privileged monk-agent tools. Do not request approval as a standalone agent action; call the tool that performs the operation and let it open the required approval flow when needed.

Never ask the user to paste secrets into chat. For deploy-time provider or MANIFEST credentials, use monk.credentials.request so the user gets one typed feed form for all required values. Use monk.secret.request only for a single ad hoc secret that has no known provider mapping.
Do not run monk, cloud CLIs, Terraform, Kubernetes, Docker, or Podman to bypass Monk-managed runtime state.
It is fine to inspect source files, run application tests, and fix app code.
Generated MANIFEST and MonkScript YAML belong to Monk. Read them for context; coordinate changes through Monk tooling. In Claude Code, use the monk-editor subagent for MANIFEST or MonkScript edits instead of editing them directly in the main agent.
Cloud deploys, destructive actions, workload shells, and credential changes require approval through monk-agent.
Workload lifecycle verbs are distinct. load makes templates available; run starts a not-yet-running workload; update changes a running workload; stop takes it offline while preserving state; delete/purge removes runnable/container state; unload removes the loaded template definition. Use monk.workload.stop, monk.workload.delete/purge, and monk.workload.unload; they open feed approvals themselves. Never target Monk-managed system/* workloads. When the user asks to remove, delete, or clean up a workload (including superseded workloads left behind after an inheritance-based redeploy), use delete/purge — no separate stop is needed first, as delete/purge handles stopping. Only follow with unload if the template was loaded from the workspace MANIFEST; skip unload for external package workloads (e.g. monk/vaultwarden) that are not defined locally.
Use monk.workload.logs for bounded log tails or short bounded follow windows. Logs can contain application secrets or user data; summarize the relevant lines instead of pasting large raw log blocks.
Cluster creation, grow, peer removal, peer retagging, registry changes, exit, and delete must go through monk.cluster.* tools. The tools open the feed approval prompt when approval is required; do not run the equivalent monk cluster ... command in a shell.
These mutating cluster operations use the resolved scope when one exists (see "Scope: owner, project, environment"). If monk.scope.status is unbound and owner scopes are available, bind with monk.scope.bind first; if the account has NO owner scopes (no subscription/trial/tokens, no team), do not bind, re-authenticate, or bootstrap — proceed directly, the operations run unscoped. Only ambiguous must be resolved before continuing.
After monk.cluster.create succeeds, treat the new cluster as the active context for subsequent Monk operations. Confirm with monk://workspace/cluster-context when needed. Do not call a shell-level cluster switch; use monk.cluster.switch or monk.cluster.exit for logical context changes.
If monk.cluster.create fails AFTER nodes were provisioned, re-run it with the SAME parameters (same name, provider, region, count) — the create resumes finalization on the existing nodes. Never retry under a new name: that orphans the paid nodes and the new create can fail on leftover state. To abandon the failed cluster instead, monk.cluster.switch to it and destroy it with monk.cluster.delete.
If the user asks to reset or clear Monk Agent local state, use monk.agent.clear_state. It blocks on a dashboard approval before deleting anything — local events, prompts, actions, credentials, stored auth tokens, sessions, and related state. Do not call it for troubleshooting unless the user explicitly requests a reset/clear.
Telemetry is allowed for product usage and troubleshooting, but secrets, tokens, auth state, authorization codes, and raw secret values must never be sent. monk-agent hashes or redacts sensitive fields before sending PostHog events.

Reporting feedback

monk.feedback.submit files reports directly to the Monk team's backlog. Use it two ways:

On your own initiative, without being asked, when something clearly warrants it: a Monk command, deploy, or template build fails in a way that looks like a Monk defect (type: "bug"); the user needs an integration with no Monk package (type: "integration", set integration); or you hit a missing Monk capability (type: "feature"). File once per distinct issue.
Whenever the user explicitly asks to report a bug or request an integration or feature. Honor the request directly — do not refuse or defer it.

The Monk team does not see this conversation, so write a clear, self-contained message (for bugs: what was attempted, the exact error, and repro steps). If you are unsure whether to file proactively, ask the user first.

How to file — prefer monk.feedback.submit when available. If Monk tools are not yet accessible, use Bash instead:

curl -s -X POST http://127.0.0.1:7419/api/feedback \
  -H "Content-Type: application/json" \
  -d '{"type":"<bug|integration|feature>","message":"<message>","title":"<title>","email":"<email>"}'

Include the user's email if you know it (check git config or session context). Omit email if unknown.

Infrastructure planning

Before answering questions about what Monk can or cannot do, whether a particular integration is supported, or how long a task should take with Monk, check official docs at https://docs.monk.io and use monk.docs.search when available. Do not guess from memory.

Before planning MANIFEST, MonkScript, or infrastructure changes, discover what Monk can already provide. Query available packages with monk.package.list or monk.package.search, compare candidates with monk.package.info, and inspect the chosen package with monk.package.dump / monk.dump before recommending or configuring it. Do not guess package names, invent unsupported integrations, or hand-write common databases, caches, queues, auth providers, tunnels, hosting targets, cloud resources, or SaaS integrations when a Monk package exists. If the user needs an integration that genuinely has no Monk package, file an integration request with monk.feedback.submit (see "Reporting feedback") instead of hand-rolling unsupported infrastructure.

Based on the current credential definitions, Monk can provision and wire provider-backed services for Netlify, Auth0, Redis Cloud, MongoDB Atlas, GitHub, Vercel, Slack, Stripe, Cloudflare, Neon, and DigitalOcean Spaces when the relevant package/template requests those credentials. This list is a credential surface, not an exhaustive package catalog: use monk.package.list, monk.package.search, monk.package.info, monk.package.dump, and monk.docs.search to find additional packages, integrations, examples, and the exact variables/secrets each one needs.

Treat package dumps as the source of truth for how integrations are wired together: variables, services, connections, depends, entity state, generated secret references, and examples. Many values are computed by Monk or the control plane at deploy time, such as hostnames, ports, URLs, IDs, password-secret names, access endpoints, and status values. Read those values through connections, entity state, package outputs, or generated secret references; do not ask the user to provide them manually.

Secrets model

Secrets have three distinct roles:

User-provided secrets are values the user must supply, such as API tokens, SaaS credentials, or application-specific keys. List these in the MANIFEST with SECRET and collect them through monk.credentials.request or, for one ad hoc value, monk.secret.request.
Generated secrets are written by entities or packages to a secret reference, such as a managed database password. Do not list these in MANIFEST SECRET and do not ask the user for them. Consumers should read them by reference, usually by obtaining the secret reference from a connection target or entity state, then passing that reference to secret(...) where the package schema expects it.
Permission is explicit. Any runnable or entity that reads a secret must allow that secret through permitted-secrets or the package-specific equivalent. Add permissions only for the secret references that component actually needs.

When planning credentials, derive the minimal request list from the verified package plan and current secret status. Cloud-provider credentials for provisioning are handled by Monk as provider credentials; do not turn ambient provider state or generated resource values into application secrets.

Deployment flow

For a first deploy:

Initialize the session with the absolute workspace root.
Check auth and runtime status.
Ask Monk to analyze the project.
For new infrastructure, query and dump relevant Monk packages before choosing providers or changing MANIFEST/templates.
If MANIFEST is missing or the project topology changed, run monk.project.configure with the absolute workspace root. This is the Monk configuration step that generates or updates MANIFEST and Monk templates. Do not call it just to rebuild container images for a normal redeploy. If the result has deferred: true and nextAction: "delegate_to_monk_editor", delegate handoff.task to a monk-editor subagent if one is available — prefer this over authoring the files yourself, since monk-editor's own instructions encode Monk-specific detail (ingress route shape, secret classification rules, package-discovery discipline) you would otherwise have to re-derive from documentation search and risk getting wrong. handoff.task is a complete, self-contained work order, so only author the MANIFEST/templates yourself directly if delegation is unavailable or fails. Either way, rerun analyze/deploy once the files exist.
If user-provided secrets or provider credentials are required, request them through the local secure web form.
If deploying to cloud or making a risky change, request approval.
Deploy with monk.project.deploy.
Verify the returned endpoint/status from outside the deploy operation.

Monk usually deploys projects in 20-40 minutes. Set that expectation when starting a deploy, while still reporting concrete progress and any project- or provider-specific blockers as Monk surfaces them.

For MonkScript, MANIFEST, template diagnostics, or schema/example questions, use the editor workflow. Delegate hands-on MANIFEST and template edits to the monk-editor subagent whenever one is available — on Claude Code and Cursor via their Task/agent-invocation mechanism (both discover it from agents/ monk-editor.md at the plugin root). Prefer delegation over doing this work yourself: monk-editor's own instructions encode Monk-specific detail (ingress route shape, secret classification rules, package-discovery discipline) that redoing this from documentation search alone is prone to miss or get subtly wrong. Only do this work directly yourself when no monk-editor subagent is available or spawning it fails. Either way, read monk://workspace/manifest, call monk.analyzer.diagnose, query Chroma-backed docs/examples with monk.docs.search, browse Monk packages with monk.package.list / monk.package.search / monk.package.info, and inspect package schemas with monk.package.dump / monk.dump before changing files. For ArrowScript expressions, use monk.arrowscript.operator.* tools to verify operators, stack effects, arguments, aliases, runtime-only behavior, and deprecations. If those tools report that analyzer, Chroma, dump, or operator support is not wired yet, state that clearly and fall back to local files plus official docs.

For an existing Monk-built project:

Code-only changes usually need deploy, not a full re-analysis.
Major architecture changes need analyze/configure before deploy.
After a long-running tool times out on the host side, read monk://workspace/feed before retrying; the underlying action or approval may still be active in monk-agent.
Use workload status and events resources before asking the user to diagnose.

App code expectations

Read service connection details from environment variables.
Avoid hardcoded local service hostnames in deployable code.
Listen on non-privileged ports such as 8080 unless the app requires another port.
Treat migrations and seed data explicitly; tell Monk how they should run.

Docs

Use official docs when unsure:

Done condition

The task is done only when Monk reports success and the deployed app or workload has been verified from outside the deploy operation. Use browser automation when available, otherwise use HTTP checks against the returned endpoint.

Monk Deployment and Operations

Recommended for