Pilot interface reference · How Mensara works

Version and evidence

Input shapes are pinned to released Core 0.20.10. The connected client's tool set and action allowlist can be narrower. Development observations are stated in each procedure; they do not qualify all clients or installations.

Read and navigate

orient {} returns principal, scope, maps and offered skills. Check the target before a write.
list_files takes optional dir, pattern and memory_view. Use dir for an authorised folder or zone ID.
read requires string path; optional mode is full or head, with limit, offset and memory_view where advertised.
get_skill requires string name; use a discoverable offered skill and follow its linked files.

Propose and inspect

check_write requires changes, an array of path/content or typed change objects. It checks the gate without landing the change.
propose_write requires the same changes; optional rationale explains the source and purpose. amends adds to an existing caller-owned held proposal when supported. Do not use it to evade review.
get_proposal accepts proposal_id, or up to 25 proposal_ids; path reads a file in the proposal. Inspect actual state and diff.
list_review_queue supports pagination and filters such as path_prefix and status. Partial or denied reads are not an all-clear.

Legacy {path, content} changes mean replacement. Typed operations include create, edit, replace, upsert, append and delete under their advertised contracts. A memory lifecycle edit needs the current revision/base. Exact transport schemas are supplied by tool discovery; never copy a server-internal token argument into a prompt or public example.

Loops

list_actions {} supplies the installed action palette and its argument/effect contracts.
list_loops {} returns stored loop summaries. get_loop requires loop_id and reads content, state and cases.
loop_compose requires strings name, description and an object spec. Its required spec keys are purpose, version, trigger, inputs, nodes, quality, escalation, autonomy, budget. The server supplies owner and shadow rollout.
get_case requires both loop_id and case_id; inspect the actual timeline and terminal outcome.

The complete no-effect example is in the loop procedure. It verifies lifecycle composition only. Real actions come from the installed palette. No loop_rehearse tool is part of this contract.

Lifecycle and review actions

act requires string action and string item_id. The meaning of the ID depends on the action: ordinary review uses card_id; app bundle review uses proposal_id; installation uses app_id; loop lifecycle uses loop_id.

For an authorised ordinary proposal approval, answer is a string containing JSON:

{"action":"queue.answer","item_id":"<card id>","answer":"{\"decision\":\"approve\"}"}

Human approval requests require their own exact user confirmation and content hash. Never fabricate that confirmation. Other lifecycle actions must be advertised and allowed by the current client. A hosted connector can expose act while refusing a particular lifecycle action.

Invitations and access

invite_member requires email and accepts only optional role: "member". It is owner-only and sends email after provider and roster checks. Pending invitation, accepted membership and effective access are separate states. If this tool is absent on the intended connection, use the owner/account membership handoff.

list_access_profiles {} is an authorised administrative read of profile definitions and assignments. Use the actual role/grant policy to interpret access; a role alone is not a complete effective-access answer.

Results and retry rules

ok: false is a refusal or failure; keep its exact bounded reason and stop at that stage.
status: "held" is waiting for review, not a landed record or installed app.
status: "applied" needs current source readback to prove the intended result.
Approval, installation, activation, scheduled execution and output acceptance are distinct postconditions.
An interrupted call has an unknown outcome until supported state/readback reconciles it. Do not retry a write or send blindly.

Practical guides for people and agents

Start with one useful job

Join the waitlist

## For agents - What Mensara is: it gives a team its own Mind, one shared memory for the team and their AI agents, built by Xanadu Labs LLC. - Status: signup is not open. A person joins the waitlist at https://app.mensara.ai/#waitlist. Agents cannot create an account or sign up. - How you can help your person: explain what Mensara does, check whether it fits a job their team repeats, and share the waitlist link. - Agent references: https://app.mensara.ai/llms.txt lists every page as Markdown and the tool input references for connected agents. --- # Pilot interface reference For agents · Pilot reference · [How it works](https://app.mensara.ai/how-it-works) Use this compact reference with the four operating procedures. Discover the actual tools on the intended connection before sending a request. [Page as Markdown](https://app.mensara.ai/how-it-works/pilot-interface-reference.md) ## Version and evidence Input shapes are pinned to released Core 0.20.10. The connected client's tool set and action allowlist can be narrower. Development observations are stated in each procedure; they do not qualify all clients or installations. ## Read and navigate - `orient {}` returns principal, scope, maps and offered skills. Check the target before a write. - `list_files` takes optional `dir`, `pattern` and `memory_view`. Use `dir` for an authorised folder or zone ID. - `read` requires string `path`; optional `mode` is `full` or `head`, with `limit`, `offset` and `memory_view` where advertised. - `get_skill` requires string `name`; use a discoverable offered skill and follow its linked files. ## Propose and inspect - `check_write` requires `changes`, an array of path/content or typed change objects. It checks the gate without landing the change. - `propose_write` requires the same `changes`; optional `rationale` explains the source and purpose. `amends` adds to an existing caller-owned held proposal when supported. Do not use it to evade review. - `get_proposal` accepts `proposal_id`, or up to 25 `proposal_ids`; `path` reads a file in the proposal. Inspect actual state and diff. - `list_review_queue` supports pagination and filters such as `path_prefix` and `status`. Partial or denied reads are not an all-clear. Legacy `{path, content}` changes mean replacement. Typed operations include create, edit, replace, upsert, append and delete under their advertised contracts. A memory lifecycle edit needs the current revision/base. Exact transport schemas are supplied by tool discovery; never copy a server-internal token argument into a prompt or public example. ## Loops - `list_actions {}` supplies the installed action palette and its argument/effect contracts. - `list_loops {}` returns stored loop summaries. `get_loop` requires `loop_id` and reads content, state and cases. - `loop_compose` requires strings `name`, `description` and an object `spec`. Its required spec keys are `purpose`, `version`, `trigger`, `inputs`, `nodes`, `quality`, `escalation`, `autonomy`, `budget`. The server supplies owner and shadow rollout. - `get_case` requires both `loop_id` and `case_id`; inspect the actual timeline and terminal outcome. The complete no-effect example is in the loop procedure. It verifies lifecycle composition only. Real actions come from the installed palette. No `loop_rehearse` tool is part of this contract. ## Lifecycle and review actions `act` requires string `action` and string `item_id`. The meaning of the ID depends on the action: ordinary review uses `card_id`; app bundle review uses `proposal_id`; installation uses `app_id`; loop lifecycle uses `loop_id`. For an authorised ordinary proposal approval, `answer` is a string containing JSON: ``` {"action":"queue.answer","item_id":"<card id>","answer":"{\"decision\":\"approve\"}"} ``` Human approval requests require their own exact user confirmation and content hash. Never fabricate that confirmation. Other lifecycle actions must be advertised and allowed by the current client. A hosted connector can expose `act` while refusing a particular lifecycle action. ## Invitations and access `invite_member` requires `email` and accepts only optional `role: "member"`. It is owner-only and sends email after provider and roster checks. Pending invitation, accepted membership and effective access are separate states. If this tool is absent on the intended connection, use the owner/account membership handoff. `list_access_profiles {}` is an authorised administrative read of profile definitions and assignments. Use the actual role/grant policy to interpret access; a role alone is not a complete effective-access answer. ## Results and retry rules - `ok: false` is a refusal or failure; keep its exact bounded reason and stop at that stage. - `status: "held"` is waiting for review, not a landed record or installed app. - `status: "applied"` needs current source readback to prove the intended result. - Approval, installation, activation, scheduled execution and output acceptance are distinct postconditions. - An interrupted call has an unknown outcome until supported state/readback reconciles it. Do not retry a write or send blindly. ## Related - [Read, correct and verify memory](https://app.mensara.ai/how-it-works/correct-memory-procedure) - [Compose and supervise a bounded loop](https://app.mensara.ai/how-it-works/build-loop-procedure) - [Build, propose and verify a governed model agent](https://app.mensara.ai/how-it-works/build-agent-procedure) - [Invite a member and verify effective access](https://app.mensara.ai/how-it-works/invite-member-procedure) Previous page: [Connect Telegram](https://app.mensara.ai/how-it-works/connect-telegram) [Join the waitlist](https://app.mensara.ai/#waitlist)