# MAO documentation > All 83 guides of the MAO docs (https://trymao.dev/docs) as Markdown, in the order of the docs' navigator. Each guide is also at its own address plus `.md`. --- # Sign in and activate MAO Connect this MAO install to your account and activate your access. Signing in connects this MAO install to your MAO account so the app can check your access. It does not sign your agent providers in. ## Sign in 1. On the licence gate or account screen, choose **Sign in**. 2. Complete the email magic-link step in your browser, then approve **Connect MAO on [device]**. 3. Return to MAO and wait for the app to finish connecting. 4. If the browser cannot return to MAO, choose **Use a code instead** in the app, copy the code shown in the browser, paste it into the account screen, and choose **Continue**. > **Tip:** If MAO cannot open your browser, choose **Copy link** and open that link yourself. Choose **Open again** on the waiting screen to reopen it later. > **Limit:** You need an MAO account to start the app. A new account has a 7-day trial; the app can work offline only while its access token is valid. Agent-provider accounts are separate. Source: https://trymao.dev/docs/getting-started/account-sign-in --- # First-run welcome Set up the app’s appearance and preferences, then open a project and meet your first agent. The first-run welcome introduces MAO and lets you choose a look and a few preferences. Some screens appear only during a trial or on the first launch. ## Complete the welcome 1. Read **Welcome** and choose **Continue**. 2. On **Choose your look**, select **System**, **Light**, or **Dark**. Set **Reduce motion** if you prefer, then choose **Continue**. 3. On **Almost ready**, review sound, the launch update check, keeping workspaces alive, and crash reports. Choose **Continue**. 4. Follow the trial or project screen if it appears. On the first launch, you can enter a workspace name, choose a Git repository, and select **Open project**. 5. On **Your first agent**, review the shortcuts for adding an agent, then choose **I'm ready**. > **Tip:** Press Enter to continue. Press Left or Backspace to go back, or Escape to choose **Skip setup**. > **Limit:** The project screen appears on the first launch, and the trial screen appears only during a trial. The welcome cannot set up a remote project. Source: https://trymao.dev/docs/getting-started/first-run-welcome --- # Getting started checklist Learn MAO by completing five real actions on the canvas. The checklist tracks five first actions and marks each one when you complete it on the canvas. It stays out of the way until you open it. ## Work through the checklist 1. Open the command palette and choose **Getting started checklist**. 2. Complete the listed actions: **Place an agent**, **Send it a first task**, **Add a note and connect it**, **Have one agent ask another**, and **Open a layer for a branch**. 3. When you are done, choose the chevron to collapse the card, or choose **Hide** or **Done** to hide it. Open **Getting started checklist** in the palette any time to return. > **Tip:** A row can show you the next action, but clicking it does not complete the step. The action itself must succeed. > **Limit:** Hiding the checklist does not clear its progress. The checklist first appears after the welcome closes, unless you open it from the palette earlier. Source: https://trymao.dev/docs/getting-started/getting-started-checklist --- # Workspaces, folders, and canvases Organize Git projects into workspaces and virtual folders in the navigator. A workspace groups canvases, with optional folders to organize them. Each canvas represents one Git repository. ## Organize projects in the navigator 1. Open the navigator with the handle on the left edge of the canvas. 2. Open the navigator menu and choose **New workspace** to create a workspace. 3. Open a workspace row menu and choose **New folder**. To nest a folder, use a folder row menu and choose **New child folder**. 4. Choose **Add project…** from the navigator or a workspace or folder menu to add a repository to that location. 5. Use the row menus to rename or move items. A canvas can be moved to another folder in its workspace or to **Move to workspace root**. > **Tip:** Use folders to group related canvases without changing your project directories. > **Limit:** A canvas must point to an existing folder with a .git directory, and the same repository cannot be added twice. Folders are virtual; they do not create directories on disk. Source: https://trymao.dev/docs/workspaces-canvases/workspace-canvas-hierarchy --- # Add or adopt a project Add a Git repository as a canvas, or bring an existing MAO project into a workspace. Adding a project creates a canvas for an existing Git repository. If MAO already has state for that repository, it uses that state in place. ## Add a project 1. Choose **Add project…** from the navigator or the canvas chrome. 2. Select the repository folder. It must already exist and contain a .git directory. 3. Choose the workspace or folder where the canvas should appear, then add the project. 4. To place a project from the legacy project list into the hierarchy, drag its row onto a workspace or folder. > **Tip:** If MAO has already used this repository, its notes and canvas state remain in place when you add it to the navigator. > **Limit:** A repository already listed cannot be added again. A trial is limited to one project. Source: https://trymao.dev/docs/workspaces-canvases/add-project --- # Switch and find workspace content Move between workspaces and canvases, or search for workspace content. Use the navigator to switch between workspaces and canvases. Its search button opens the shared command palette with Workspaces already selected. ## Navigate to a canvas 1. Open the navigator with its handle on the left edge of the canvas. 2. Expand a workspace or folder row to show its canvases. 3. Choose a canvas row to open it. 4. To search, select the navigator’s search control, enter a name, and choose a workspace result. > **Tip:** The shared palette can search across more than workspaces. Clear the **Workspaces** scope to broaden the search. > **Limit:** Navigator search is not full-text search of workspace files or notes. Numbered terminal jumps follow creation order, not assigned slots. Source: https://trymao.dev/docs/workspaces-canvases/workspace-navigation --- # Reopen saved workspace state Return to your canvases and persistent content after quitting MAO. MAO saves workspace content locally, including canvas layouts, nodes, notes, and connections. Reopen the workspace from the navigator when you return. ## Reopen your workspace 1. Launch MAO and choose the workspace and canvas you want in the navigator. 2. To keep background workspaces running when you switch away or quit, open Settings and enable **Keep workspaces alive**. 3. Reopen the canvas later from its row in the navigator. > **Limit:** Undo history and viewport movement are not restored. Terminal processes restart when you reopen; MAO does not resurrect the old process. Source: https://trymao.dev/docs/workspaces-canvases/workspace-persistence --- # Pan and zoom the canvas Move around a large workspace, zoom in on your team, and bring the whole canvas into view. ## Pan across the workspace Drag an empty part of the canvas to move the view. Your nodes stay where they are; only the camera moves. If a terminal has the keyboard, its scrollback receives the wheel. Hold Ctrl on Windows and Linux or ⌘ on macOS while scrolling to zoom the canvas instead. > **Tip:** Start a pan from open canvas between nodes. This keeps the gesture away from node controls and terminal text. ## Choose a zoom level Use the **−** and **+** controls beside the zoom percentage in the lower-right corner. You can also zoom with a trackpad gesture or the mouse wheel. The current percentage gives you a quick reference as you move between a close-up and a full workspace view. ## Find the whole canvas Open the command palette and choose **Fit all** to frame your nodes. The minimap gives you another way to move: click a place on its map to center the canvas there, or drag the viewport marker to pan continuously. > **Limit:** Panning and zooming are navigation. They do not create an undo step. ## Keep scrolling in the right place When a terminal is focused, normal scrolling belongs to its output. Use Ctrl + wheel on Windows and Linux, or ⌘ + wheel on macOS, when you mean to zoom the canvas around that terminal. Source: https://trymao.dev/docs/canvas-basics/canvas-pan-zoom --- # Pan, zoom, and fit the canvas Move around the canvas and quickly frame all nodes or the current selection. Pan and zoom to move around a large canvas, then fit the whole layout or just a selection into view. For the zoom controls and minimap, see [Pan and zoom the canvas](https://trymao.dev/docs/canvas-basics/canvas-pan-zoom). ## Frame the canvas 1. Drag an empty area of the canvas to pan. 2. Use the **−** and **+** controls by the zoom percentage, or use the mouse wheel or trackpad to zoom. 3. Press Shift + 1 to fit all nodes. Press Shift + 2 to fit the current selection. 4. You can also open the command palette and choose **Fit all**. > **Tip:** Hold Ctrl while scrolling on Windows or Linux, or Cmd on macOS, to zoom the canvas around a focused terminal. > **Limit:** A terminal with keyboard focus receives its own wheel and keys. Panning, zooming, and fitting do not create undo steps. Source: https://trymao.dev/docs/canvas-basics/pan-zoom-fit --- # Minimap Use the overview map to move quickly across a large canvas. The minimap shows node frames and connections alongside the part of the canvas currently in view. Use it to move the main canvas without losing your place. ## Navigate with the minimap 1. Find **Overview** in the lower-right corner of the canvas. 2. Click a place on the map to center the canvas there. 3. Drag the viewport rectangle to pan continuously across the canvas. > **Limit:** The minimap is an overlay and is not saved. It shows node frames rather than detailed node content. Source: https://trymao.dev/docs/canvas-basics/canvas-minimap --- # Select, move, and resize nodes Select one or more canvas nodes, move them together, or resize a node. Select nodes to move or resize them on the canvas. You can select a group and move its unlocked nodes together. ## Select nodes 1. Click a node header, card, or shape to select it. Click empty canvas to clear the selection. 2. Hold Shift and click nodes to add them to or remove them from the selection. You can also drag on empty canvas to draw a selection box; hold Shift while dragging to add to the current selection. 3. Press Ctrl + A on Windows or Linux, or Cmd + A on macOS, to select all nodes. ## Move and resize 1. Drag a selected node by its header or frame to move it. When several nodes are selected, drag one of them to move the group. 2. Select a node and drag its resize handle to change its size. > **Tip:** Hold Space while dragging to pan the canvas without changing the selection. > **Limit:** A terminal or text editor with keyboard focus keeps its own typing and selection. Locked nodes cannot be resized or moved. In a group move, a locked node stays in place while unlocked nodes move. Source: https://trymao.dev/docs/canvas-basics/canvas-select-move-resize --- # Place canvas nodes Add terminals, notes, project files, browser portals, and device portals to a canvas. Canvas nodes give you places to run agents, keep notes, browse a site, or inspect project files. Add one from the tool rail, then place it on the canvas. ## Place a node 1. Open the tool rail on the right edge of the canvas. 2. Choose **New terminal or agent**, **New note**, **New file tree**, **New portal**, or **New device portal**. 3. Finish any setup sheet, then place the draft where you want it. 4. To start terminal or agent placement from the keyboard, press Ctrl + T on Windows or Linux, or Cmd + T on macOS. > **Tip:** Place related nodes near one another, then connect the agents, notes, and portals that need shared context. > **Limit:** Available node types depend on the project, agent provider, browser, and device tools available on your system. Source: https://trymao.dev/docs/canvas-basics/create-canvas-nodes --- # Focus a node Magnify one node and quiet the surrounding node chrome while you work. Focus mode magnifies a supported node while leaving the rest of the canvas available. It hides surrounding node chrome so the selected work is easier to follow. ## Enter focus mode 1. Select a terminal, note, file, or portal node. 2. Double-click its header, choose **Focus** on the node bar, or choose **Focus selected node** from the command palette. 3. You can also press F when the canvas has focus. The focus chord works even while a terminal is focused: Ctrl + Shift + Enter on Windows or Linux, or Cmd + Shift + Enter on macOS. ## Leave focus mode 1. Choose **Exit focus** on the node bar or **Exit focus mode** in the command palette. 2. You can also use the same focus chord, choose the exit pill, or press Escape if the key reaches the canvas. > **Limit:** Focus magnification stops at 2× and does not resize the node or save a new canvas layout. Drawings and draft terminals cannot be focused. Source: https://trymao.dev/docs/canvas-basics/canvas-focus-mode --- # Lock nodes in place Keep a node’s position and size from changing during canvas edits. Locking protects a node’s position and size while you work around it. You can still select, focus, type into, and connect a locked node. ## Lock or unlock a node 1. Select one or more nodes. 2. With the canvas focused, press Ctrl + L on Windows or Linux, or Cmd + L on macOS. You can also choose **Lock** in the command palette or **Lock position** from a node’s context menu. 3. To unlock, use the same shortcut or choose **Unlock** in the palette or **Unlock position** from the node menu. > **Tip:** If a selection contains both locked and unlocked nodes, the toggle locks all of them. If every selected node is locked, the toggle unlocks them all. > **Limit:** A focused terminal uses Ctrl + L to clear its screen. Locked nodes cannot be moved, resized, or deleted; a bulk delete is refused if any selected node is locked. Source: https://trymao.dev/docs/canvas-basics/canvas-lock-nodes --- # Delete or prompt a selection Delete selected nodes or send one prompt to several agents at once. The selection action bar and command palette can act on multiple selected nodes. You can also delete a single selected node. ## Act on selected nodes 1. Select the nodes you want to change. 2. Choose **Delete N selected nodes** to remove the selection, or choose **Send prompt to N agents** to compose a prompt for the selected agents. 3. If the prompt misses an agent, review the result and choose **Retry missed agents only** to try those recipients again. 4. For a single selected node, choose **Delete** from its node bar or menu. > **Limit:** MAO asks for confirmation before deleting live agents. If any selected node is locked, the whole bulk delete is refused. A prompt reports agents that did not receive it. Source: https://trymao.dev/docs/canvas-basics/bulk-node-actions --- # Undo and redo canvas edits Undo or redo recent node, connection, and agent preset changes. Undo and redo reverse recent canvas edits, including node, connection, and agent preset changes. Canvas history is kept in memory. ## Undo an edit 1. Make sure the canvas has keyboard focus. 2. Press Ctrl + Z on Windows or Linux, or Cmd + Z on macOS. You can also choose **Undo** from the command palette. ## Redo an edit 1. Press Ctrl + Shift + Z or Ctrl + Y on Windows or Linux. On macOS, use Cmd + Shift + Z or Cmd + Y. 2. You can also choose **Redo** from the command palette. > **Tip:** Moving or resizing a node is one history step after you finish the drag. > **Limit:** History is not saved and clears when you switch workspaces. Panning and zooming are not undoable. Undoing a deleted terminal creates a new process; undoing a deleted note node leaves its Markdown file in place. Source: https://trymao.dev/docs/canvas-basics/canvas-undo-redo --- # Nudge a selection Move selected nodes by grid cells with the arrow keys. When the canvas has focus, arrow keys move selected nodes by grid cells. If nothing is selected, the same keys pan the view. ## Nudge nodes 1. Select one or more nodes and make sure the canvas has focus. 2. Press an arrow key to move the selection one grid cell. 3. Hold Shift with an arrow key to move five grid cells. > **Tip:** A series of nudges made within 600 milliseconds is grouped into one undo step. > **Limit:** Ctrl, Cmd, and Alt do not change the nudge distance. Arrow-key panning is navigation and is not undoable. Source: https://trymao.dev/docs/canvas-basics/keyboard-nudge --- # Tidy up nodes Arrange a selection or the whole canvas into a more orderly layout. Tidy up arranges selected nodes, or the whole canvas when nothing is selected. It keeps groups together while laying out the frames. ## Tidy a layout 1. Select at least two nodes if you want to arrange only part of the canvas. 2. Open the command palette and choose **Tidy up**. 3. Review the layout. Use Undo if you want to return to the previous arrangement. > **Limit:** A request with exactly one selected node is refused. Locked nodes do not move; drawings are left out unless selected. One tidy action creates one undo step. Source: https://trymao.dev/docs/canvas-basics/tidy-canvas --- # Collapse nodes at overview zoom See compact status cards when you zoom out, then zoom back in for full node surfaces. At overview zoom, MAO replaces detailed node surfaces with compact cards. Zoom in again to return to the full nodes. ## Switch between overview and full nodes 1. Zoom out until node surfaces collapse into compact cards. 2. Read each card’s identity and status while you scan the layout. 3. Zoom back in to reopen the detailed node surfaces. > **Limit:** The collapse and reopen thresholds are separated to keep cards from flickering as you zoom. Browser and device streams stop when their nodes are collapsed or not painted. Source: https://trymao.dev/docs/canvas-basics/semantic-zoom --- # Follow connected context Emphasize a connected group and recede unrelated nodes while you inspect it. Connection focus keeps connected neighbors prominent while unrelated nodes recede. It changes the view temporarily and does not change the connection graph. ## Focus a connected group 1. Select a node that has connections. 2. Press Alt on Windows or Linux, or Option on macOS, to emphasize its connected group. 3. Press the same key again to narrow the emphasis back to the selected node. > **Limit:** Connection focus is a temporary visual mode. It does not create a connection or save a preference. Source: https://trymao.dev/docs/canvas-basics/connection-focus --- # Jump along connections or attention Move between connected nodes or jump to the next agent that needs attention. Use keyboard shortcuts or palette actions to move between connected nodes and agents that need attention. ## Jump between connected nodes 1. Select a node with at least one connection. 2. Press Ctrl + ] or Ctrl + [ on Windows or Linux. On macOS, use Cmd with the bracket key. 3. You can also choose **Next connected** or **Previous connected** from the command palette. ## Jump to attention 1. Press Ctrl + Shift + . on Windows/Linux or Cmd + Shift + . on macOS to jump to the next agent that needs attention. 2. You can also choose **Jump to next attention** in the palette, or press Tab while the attention rail has canvas focus. > **Limit:** Connected-node jumps need a selected wired node. Attention jumps wrap across the open canvas family; Tab cycles only the current canvas attention rail. Source: https://trymao.dev/docs/canvas-basics/canvas-focus-jumps --- # Connect canvas nodes Draw explicit connections so agents can find one another and reach the notes or portals they need. ## Connect from an agent Select a terminal, choose **Connect** on its node bar, then pick a destination from the list. You can also activate the canvas **Connect** tool and choose both endpoints. MAO draws a wire between them. ## Give an agent the context it needs Connect one agent to another to let them discover each other and route tasks and results. Connect a terminal to a note when that agent needs to read or update it. A terminal-to-portal connection grants that terminal access to the browser or device portal. > **Tip:** Name notes and terminals by their job. The Connect list uses those names, so clear labels make the destination easier to pick. ## Remove access Select the agent and disconnect the edge from its node bar or menu. The wire represents an access grant: when it is gone, that terminal no longer has that peer or context connection. > **Limit:** A wire does not expose everything on the canvas. Each terminal can reach only the peers, notes, or portals connected to it. Source: https://trymao.dev/docs/canvas-basics/canvas-connections --- # Save and revisit canvas views Save named viewport positions and return to them with a shortcut or palette action. Saved views remember where the camera is pointed on a canvas. They do not save or rearrange the nodes themselves. ## Save and revisit a view 1. With the canvas focused, press Ctrl + Alt + a number from 1 to 9 on Windows or Linux. On macOS, use Cmd + Option and the number. 2. Return to a saved view with Alt + a number on Windows or Linux, or Option + a number on macOS. 3. To manage views by name, open the command palette and choose **Save view…**, **Go to view: name**, or **Delete view: name**. > **Limit:** Each canvas has nine saved view slots. A view saves the camera position; a saved arrangement stores nodes and connections. Source: https://trymao.dev/docs/canvas-basics/saved-views --- # Search actions and canvas content Find workspaces, nodes, notes, layers, saved views, and actions in one palette. The command palette searches the current canvas and workspace for actions and content. It also gives you a quick way to browse recent items and common actions. ## Find an action or item 1. With the canvas focused, press Ctrl + K or Ctrl + P on Windows/Linux; press Cmd + K or Cmd + P on macOS. 2. Type a query, then choose a scope from the **Looking for** chips if you want to narrow results. 3. Use Up and Down to move through results and Enter to open one. 4. Type @ followed by a name, then press Tab to complete a matching agent, note, or workspace. 5. To search workspaces from the navigator, choose its search control; the palette opens with **Workspaces** selected. > **Tip:** Open the palette without typing to browse Recent, Quick actions, and Notes. > **Limit:** Results reflect information the canvas knows about and palette overlay state is kept in memory. Source: https://trymao.dev/docs/command-palette/command-palette --- # Keyboard shortcut reference Find keyboard shortcuts for canvas navigation, editing, chat, terminals, and portals. These shortcuts work when the relevant canvas, terminal, composer, or portal has focus. On Windows and Linux, use Ctrl; on macOS, use Cmd where shown. ## Canvas and tools 1. Open the palette with Ctrl + K or Ctrl + P on Windows/Linux; on macOS use Cmd + K or Cmd + P. 2. Toggle the navigator with Ctrl + \ on Windows/Linux or Cmd + \ on macOS. Create a terminal or agent with Ctrl + T or Cmd + T. 3. Choose Select, Rectangle, Pen, Label, or Text with V, R, P, L, or T. Hold Space while dragging to pan. 4. Use the arrow keys to nudge selected nodes or pan. Hold Shift to nudge five grid cells. Select all with Ctrl + A or Cmd + A. 5. Undo with Ctrl + Z or Cmd + Z. Redo with Ctrl + Shift + Z or Ctrl + Y on Windows/Linux; use Cmd + Shift + Z or Cmd + Y on macOS. 6. Fit all nodes or the selection with Shift + 1 or Shift + 2. Focus the selected node with F or Ctrl + Shift + Enter on Windows/Linux; use Cmd + Shift + Enter on macOS. ## Navigation and notes 1. Step to the next or previous connected node with Ctrl + ] or Ctrl + [ on Windows/Linux; use Cmd + ] or Cmd + [ on macOS. 2. Jump to the next attention item with Ctrl + Shift + . on Windows/Linux or Cmd + Shift + . on macOS. Tab cycles the current canvas attention rail. 3. Return focus to the layer rail with Ctrl + Up on Windows/Linux or Cmd + Up on macOS. Switch to the previous layer with Ctrl + Shift + Up or Cmd + Shift + Up. 4. Save a view with Ctrl + Alt + a number from 1 to 9 on Windows/Linux. On macOS, use Cmd + Option plus the number. Return with Alt plus the number or Option plus the number on macOS. 5. Stack notes into a binder with Ctrl + Shift + B on Windows/Linux or Cmd + Shift + B on macOS. ## Composer, terminal, and browser 1. In the prompt composer, press Enter to send or Shift + Enter for a new line. Send with Ctrl + Enter on Windows/Linux or Cmd + Enter on macOS. 2. Copy terminal text with Ctrl + C on Windows, Ctrl + Shift + C on Linux, or Cmd + C on macOS. Paste with Ctrl + V on Windows, Ctrl + Shift + V on Linux, or Cmd + V on macOS. 3. Scroll terminal history with Shift + PageUp/PageDown and Shift + Home/End on Windows/Linux. On macOS, use Cmd + PageUp/PageDown and Cmd + Home/End. 4. In a browser portal, use Ctrl + L, Ctrl + T, Ctrl + R, or Ctrl + W on Windows/Linux. On macOS, use the same keys with Cmd. Navigate back or forward with Alt + Left/Right on Windows/Linux or Option + Left/Right on macOS. > **Limit:** Shortcuts are not configurable in this shipped slice. A focused terminal, editor, composer, or portal receives its own input. Source: https://trymao.dev/docs/keyboard-shortcuts/canvas-shortcuts --- # Choose and customize the theme Select a system, light, or dark theme and optionally adjust local theme tokens. MAO can follow the system appearance or use a light or dark theme. You can also add local theme token overrides. ## Choose a theme 1. Open **Settings** and select **Appearance**. 2. Choose **Theme**, then pick **System**, **Light**, or **Dark**. 3. To customize the palette, edit the local **theme.json** file. 4. You can also choose **Theme: dark**, **Theme: light**, or **Theme: system** from the command palette. > **Note:** Local token overrides update live and layer over Satin’s built-in theme. > **Limit:** Invalid token values fall back to the built-in theme. Source: https://trymao.dev/docs/settings-backups-updates/appearance-and-theme --- # Set sound cues and reduced motion Adjust synthesized interaction sounds, their volume, and reduced-motion behavior. MAO synthesizes short interaction sounds and lets you adjust their volume. Reduced motion is available in the same settings area. ## Adjust sound and motion 1. Open **Settings**. 2. Adjust **Sound** and its volume. 3. Turn on **Reduced motion** if you prefer fewer animated transitions. > **Note:** Bridge-originated interaction sounds play at half volume. > **Limit:** These settings do not control audio from a program running in a terminal. Source: https://trymao.dev/docs/settings-backups-updates/sounds-and-motion --- # Keep background workspaces alive Choose whether MAO retains background workspaces when you switch away or quit. The workspace retention setting controls whether MAO keeps background workspaces alive. You can set it during first run or change it later in Settings. ## Change workspace retention 1. Open **Settings**. 2. Find **Keep workspaces alive**. 3. Turn the setting on or off. 4. You can also choose the same setting on the **Almost ready** first-run screen. > **Limit:** Keeping workspaces alive does not guarantee process recovery after a crash or machine shutdown. Source: https://trymao.dev/docs/settings-backups-updates/workspace-retention --- # Choose notification sources Choose whether routines, agents, or layers can notify you. MAO can notify you about routine runs, agent requests, and layer attention. Each source has a separate setting. ## Choose notification sources 1. Open **Settings** and choose **Notifications**. 2. Turn **Notify when a routine fires** on or off. 3. Set **Allow agents to notify you** and **Notify when a layer needs you** as needed. > **Note:** Agent notifications are off by default. Terminal attention notices include the node title and a fixed reason label, never terminal output. > **Limit:** Agent notification delivery is unavailable on Windows. Source: https://trymao.dev/docs/settings-backups-updates/notification-settings --- # Opt in to diagnostics Enable limited product diagnostics and copy a local report when needed. Diagnostics are optional and off by default. The diagnostics view also lets you copy a local report for inspection. ## Enable diagnostics 1. Open **Settings** and choose **Diagnostics**. 2. Review the information shown there. 3. Turn on **Diagnostics** if you want to opt in. 4. Choose **Copy diagnostics** from the canvas overflow menu to copy a report. > **Limit:** Diagnostic reports exclude prompts, terminal output, and note contents. MAO does not record session replay. Source: https://trymao.dev/docs/settings-backups-updates/diagnostics --- # Back up or restore a workspace Create a local MAO backup archive or restore its contents from a backup file. MAO can create local **.mao-backup** archives and restore them as a new workspace or into a closed workspace. Automatic backups are optional. ## Create or restore a backup 1. Open **Settings** and choose **Backups**. 2. To create one now, choose **Back up now**. You can also enable **Automatic backups**. 3. Choose **Show folder** to locate archives or **Restore from file…** to choose one. 4. Review the restore sheet and choose whether to restore as a new workspace or replace a closed workspace. 5. Use **Delete every backup for ** to remove that workspace’s backup history. > **Note:** An Orchestrator can use **mao backup create** and **mao backup list**. > **Limit:** Automatic backups are off by default and keep at most 14 days or 512 MiB. Worktrees, provider accounts, credentials, task records, and browser cookies are excluded. The target must be closed before replacement. Source: https://trymao.dev/docs/settings-backups-updates/backups-and-restore --- # Check for and install updates Check for a stable MAO release, read release notes, and restart to install an update. MAO can check for a stable release and download an update. You can choose whether it checks automatically when the app launches. ## Check and install 1. Open **Settings**. 2. Turn on **Automatic update check** if you want MAO to check at launch. 3. Choose **Check for updates** to check now, or **Release notes** to read about a release. 4. When an update is ready, download it and choose **Restart** to install. > **Note:** Launch checks run quietly. If a check fails, choose **Retry**. > **Limit:** Manual update checks require a licensed account and are unavailable during the trial. Source: https://trymao.dev/docs/settings-backups-updates/updates --- # Run a shell or agent Start a shell or supported coding agent in a terminal node. Terminal nodes run a shell or supported coding-agent command in the project directory. Choose a preset, configure it, and place the node on the canvas. ## Start a terminal or agent 1. Choose **New terminal or agent** from the tool rail, or press Ctrl + T on Windows or Linux, or Cmd + T on macOS. 2. In the setup sheet, choose **Shell**, a provider preset, or **Custom**. 3. Review the launch settings, finish setup, and place the node. > **Tip:** Agent sign-in and model selection stay in the provider’s own account and configuration. > **Limit:** MAO launches an explicit program and argument list in the project root. Custom commands are not passed through a shell. Source: https://trymao.dev/docs/terminals-agents/terminal-and-agent-nodes --- # Read process and attention status Tell whether a terminal process finished, failed, or needs your attention. A terminal’s status comes from its process exit and the terminal bell. ACP sessions can provide additional structured waiting and approval states. ## Read a terminal’s status 1. Check the status mark on the terminal node. A successful process exit is **completed**; a non-zero exit or launch or I/O error is **failed**. 2. If the node raises attention, acknowledge it on the canvas or choose **Jump to next attention** from the command palette. 3. If an unselected terminal raises a new attention reason, MAO may also send a desktop notification. > **Limit:** Silence or idle output does not mean a PTY process is complete. PTY attention comes from the bell; waiting and approval-required status need a structured source such as ACP. Windows desktop notifications are unavailable. Source: https://trymao.dev/docs/terminals-agents/session-status --- # Select and copy terminal text Select terminal text with the mouse, then copy it to the clipboard. Terminal text selection follows terminal cells, so it stays attached to the output as new text arrives. Use the copy action when you want the selection on the regular clipboard. ## Select and copy text 1. Drag across terminal text to select it. Double-click a word or triple-click a soft-wrapped line. 2. Copy with Ctrl + C on Windows, Ctrl + Shift + C on Linux, or Cmd + C on macOS. 3. You can also open the terminal node menu and choose **Copy**. > **Tip:** A single Ctrl-click or Cmd-click opens a URL in the terminal. > **Limit:** On Linux and FreeBSD, finishing a selection also writes the primary selection. Only the explicit copy shortcut or **Copy** menu action writes the regular clipboard. Source: https://trymao.dev/docs/terminals-agents/terminal-selection-copy --- # Paste safely into a terminal Review a risky multi-line paste before it reaches a terminal program. MAO holds some terminal pastes for confirmation so pasted lines do not run as soon as they arrive. Review the text before sending it to the program. ## Paste into a terminal 1. Paste with Ctrl + V on Windows, Ctrl + Shift + V on Linux, or Cmd + V on macOS. You can also use the node menu or middle-click to paste the primary selection. 2. If MAO shows a paste card, choose **Paste** or press Enter to confirm. 3. Choose **Cancel** or press Escape to discard the held paste. > **Limit:** A multi-line paste without bracketed-paste support waits for confirmation. A lone carriage return also counts as a line break. Pasting returns the terminal view to the bottom. Source: https://trymao.dev/docs/terminals-agents/terminal-paste-protection --- # Handle terminal clipboard requests Review clipboard reads requested by terminal programs and control access. Terminal programs can use OSC 52 to write the clipboard or request clipboard text. MAO asks before giving a program access to read it. ## Respond to a clipboard request 1. When the clipboard card appears, review the text the program would receive. 2. Choose **Allow** to answer the read request with the displayed clipboard text, or **Deny** to refuse it. 3. The terminal applies OSC 52 clipboard writes from the program. > **Limit:** Pressing Enter never approves a clipboard read. A held paste from you takes priority over a program’s read request. Source: https://trymao.dev/docs/terminals-agents/terminal-clipboard-permissions --- # Browse terminal scrollback Move through recent terminal output, including the output left after a process exits. Scroll through a terminal’s recent output to review earlier commands or results. A terminal keeps a smaller history after its process exits. ## Browse output 1. Scroll inside the terminal to move through its output. 2. Press Shift + PageUp or PageDown to move by a page. 3. Press Shift + Home or End to jump to an end of the scrollback. On macOS, use Cmd instead of Shift. > **Limit:** A running terminal keeps 10,000 lines. After the process exits, it keeps 1,000 lines. Source: https://trymao.dev/docs/terminals-agents/terminal-scrollback --- # Use terminal mouse and cursor modes Let a mouse-enabled terminal program receive pointer input and show its requested cursor. Some terminal programs ask MAO to report pointer input and draw a particular cursor shape. When the terminal is focused, MAO forwards those gestures in the format the program requested. ## Use a mouse-enabled terminal 1. Focus the terminal and use the program’s mouse-enabled controls. 2. Hold Shift when you want MAO to handle a local canvas gesture instead of sending the mouse action to the program. > **Limit:** The click that focuses a terminal is not forwarded. A reported right-click belongs to the program and does not open MAO’s node menu. Cursor blinking runs only for the focused, visible, expanded terminal. Source: https://trymao.dev/docs/terminals-agents/terminal-mouse-rendering --- # Resume or recover an agent session Resume a supported provider session or choose how to recover after a quick resume failure. MAO keeps provider session identity separate from the local terminal process. Supported providers can resume a recorded session when you reopen or restart its agent node. ## Recover a session 1. Reuse the existing agent node to resume its recorded session. 2. If resume fails shortly after launch, choose **Start fresh**, **Resume by ID**, or **Pick a session** when the provider offers a picker. 3. Copy the session ID from the node menu or agent sheet if you need to keep it. > **Limit:** Claude Code, Grok, and Codex have session ID capture paths. OpenCode and Antigravity do not yet. Provider transcripts and authentication stay outside workspace JSON. Source: https://trymao.dev/docs/terminals-agents/provider-session-recovery --- # Receive attention notifications Notice when an unselected terminal needs your attention. When an unselected terminal raises a new attention reason, MAO can send a short desktop notification. The canvas also marks the terminal so you can return to it. ## Respond to terminal attention 1. Open the marked terminal on the canvas and acknowledge its attention. 2. To ask an agent to send a notification, enable **Allow agents to notify you** in Settings and use the agent’s notification command. > **Limit:** Notifications show the node title and a fixed reason label, never terminal output. Missing notification tooling is ignored; agent notifications are off by default and unavailable on Windows. Source: https://trymao.dev/docs/terminals-agents/attention-notifications --- # Configure agent launch presets Choose a built-in agent, shell, or custom command and adjust how its node launches. A launch preset chooses the program MAO starts in a terminal node. You can change the preset or its options later without replacing the node. ## Set up a terminal or agent 1. Choose **New terminal or agent**, or press Ctrl + T on Windows/Linux or Cmd + T on macOS. 2. Choose **Shell**, a listed provider, or **Custom**. 3. Complete the setup sheet and place the node on the canvas. 4. To change a running node, choose **Configure** on its node bar or **Change preset** in its menu. 5. Edit the name, model, account, role, Orchestrator setting, or **Launch options**, then save. > **Note:** Changing a preset restarts the terminal process while keeping the node identity and bridge credentials. > **Limit:** MAO starts a program with an explicit command and arguments in the project root. Custom commands are not run through a shell. MAO passes provider flags but does not edit provider configuration; reserved arguments are rejected. Source: https://trymao.dev/docs/agent-presets-accounts-roles/agent-presets --- # Add and choose provider accounts Save a provider account locally and assign it to an agent node. Provider accounts let an agent node use a saved directory, API key, or endpoint credential. These accounts are separate from your MAO sign-in. ## Add an account 1. Open an agent’s setup sheet and choose **Add account…** or **Manage accounts**. 2. Choose the credential type the provider supports: **Directory**, **API key**, or **Endpoint**. 3. Enter the requested account details and save. 4. Return to the agent node and choose the account from its **Account** menu. 5. To maintain saved accounts, open **Accounts**, then choose **Edit account**, **Remove account**, or **Done**. > **Note:** Provider account support varies. Changing an account can restart its agent process. > **Limit:** Credentials stay in local MAO account storage and are excluded from workspace backups. Source: https://trymao.dev/docs/agent-presets-accounts-roles/agent-accounts --- # Rotate an account’s API keys Add multiple masked keys to a supported provider account and try the next key. A key pool keeps an ordered list of API keys for a supported provider account. You can move to the next key from the agent node when a request needs a different credential. ## Add keys and switch 1. Open **Accounts** and edit the provider account. 2. Add the API keys to its key pool. The saved values are masked. 3. When you want to try another key, choose **Restart with next key · n of N** on the agent node. 4. Check the node after it starts to see whether the new key works. > **Note:** MAO advances the pool only after the child process starts. > **Limit:** Key-pool support depends on the provider integration. Credentials are not included in logs or diagnostics. Source: https://trymao.dev/docs/agent-presets-accounts-roles/account-key-pools --- # Save and assign agent roles Reuse a named instruction block on an agent node or manage roles with the mao CLI. A role is a reusable Markdown instruction block for an agent. Assign a role from the agent sheet or manage roles with the MAO command line. ## Save and assign a role 1. Open the agent’s instructions sheet and choose **Save as role**. 2. Give the role a name and save it. 3. Select the agent node and choose a role chip in its agent sheet. **Builder** and **Reviewer** are available built-in roles. 4. To manage roles from a connected terminal, use the `mao role list`, `mao role show`, `mao role create`, `mao role edit`, `mao role write`, or `mao role assign` commands. > **Note:** Assigning a role does not restart the agent session. > **Limit:** Custom role instructions are limited to 32 KiB. Built-in roles cannot be edited. MAO automatically adds role instructions to ACP prompts; PTY-only agents do not receive them automatically. Source: https://trymao.dev/docs/agent-presets-accounts-roles/agent-roles --- # Switch an agent node to chat mode Use an in-app conversation on an agent node and return to its terminal when needed. Chat mode gives you a person-to-agent conversation on an agent node alongside its terminal view. Switch between the two faces from the node or the command palette. ## Open chat 1. Select a running agent node. 2. Choose **Chat** on its node bar or in its context menu. 3. Type into the chat composer and send your message. 4. To return to the process view, choose **Terminal view** on the node or from the palette. > **Tip:** The palette includes **Chat mode** and **Terminal view** actions for the selected agent. > **Limit:** Shells, draft nodes, and remote nodes do not support chat mode. The `mao say` command sends to the current node and requires its chat mode to be open. Source: https://trymao.dev/docs/chat-mode-threads/framed-chat --- # Keep separate chat threads Organize an agent’s chat into color-coded threads and choose where its next answer appears. Each chat-capable agent has seven color-coded threads. The active marker shows which thread will receive the next answer. ## Switch threads 1. Open the agent’s chat face. 2. Select a thread from the thread selector or ribbon. 3. To rename or manage a thread, secondary-click its entry in the ribbon and choose an available menu action. 4. Check the active marker before sending the next message. > **Note:** Each agent has its own threads. A canvas connection does not grant another agent access to them. > **Limit:** MAO refuses or asks before switching threads during an open turn. How a provider resumes its session varies by agent. Source: https://trymao.dev/docs/chat-mode-threads/chat-threads --- # Attach files and images to chat Send files with a prompt and open file attachments from an agent’s reply. You can attach files to a chat prompt, and an agent can include files with its reply. Supported images appear inline; other attachments open with your system’s file handler. ## Add and open attachments 1. Open an agent’s chat and use the prompt composer’s attachment control to add files. 2. Review the attachment chips, then send the prompt. 3. To open a non-image file from an agent reply, select its attachment card. > **Note:** PNG, JPEG, GIF, and WebP images can render inline. Agents can also attach files with `mao say --file` or `mao say --attach`. > **Limit:** A message supports up to 8 files, each up to 25 MiB. HEIC files are refused. Chat history is compacted after it reaches 16 MiB and reduced to 12 MiB. Source: https://trymao.dev/docs/chat-mode-threads/chat-files-images --- # Use a structured ACP chat Enable ACP chat for a supported provider and hand the provider session between chat and terminal. ACP chat uses an agent’s structured Agent Client Protocol session while keeping its provider session available to the terminal view. The setting is off until you enable it. ## Turn on ACP chat 1. Open **Settings** and enable **Chat over ACP (beta)**. 2. Enable the row for the provider you want to use. 3. Select an eligible agent node and choose **Chat**. 4. If the agent asks for permission, choose an option on the permission card. Choose **Stop** or press Escape to cancel. 5. Choose **Terminal view** to hand the provider session back to the terminal. > **Note:** Claude Code is enabled by default in the provider list. You must enable ACP chat yourself; Antigravity cannot be enabled. > **Limit:** Switching during an open turn can be refused or require confirmation. Shell and Custom presets use framed chat instead. The ACP adapter requires a supported runtime. Source: https://trymao.dev/docs/chat-mode-threads/chat-over-acp --- # Compose prompts with context Draft a prompt for selected agents with connected references and file attachments. The prompt composer sends a message to one or more selected agents. You can reference connected agents or notes, attach files, and keep a draft for each node. ## Send a prompt 1. Select an agent and open **Send prompt**, or use the composer at the bottom of the canvas. 2. Type your prompt. Enter **@** to choose a connected agent or note to reference. 3. Add any files you want to attach and check the recipient list. 4. Press Enter to send. Use Shift + Enter for a new line, or Ctrl + Enter on Windows/Linux and Cmd + Enter on macOS to send. > **Limit:** Mentions are limited to connected context. You can attach up to 8 files; inline text is limited to 64 KiB, and note reads are limited to 64 KiB. Draft text persists per node, but attachment paths rather than file contents are saved. Source: https://trymao.dev/docs/prompt-composer/prompt-composer --- # Connect agents, notes, and portals Create explicit canvas connections that give an agent access to a peer or context node. Canvas connections tell agents which other nodes they can discover. An edge grants access only to the node at its other end. ## Connect two nodes 1. Select an agent terminal. 2. Choose **Connect** on its node bar. 3. Choose the destination agent, note, or portal. 4. To remove the edge, choose **Disconnect** on the node bar or in its menu. 5. An Orchestrator can also connect named nodes with `mao connect `. > **Note:** Connect only the context the agent needs. A wire does not expose unrelated canvas content. Source: https://trymao.dev/docs/connections-orchestration-mao-cli/node-connections --- # Discover connected peers List the peers and context nodes available to an agent through the local bridge. The MAO bridge lists peers and context an agent can reach through its connections. Use the displayed names when you send tasks or read notes. ## List available peers 1. Open a connected agent’s terminal. 2. Run `mao list`. You can also use `mao peers`. 3. Use a listed peer name in a task command, or use a listed note ID with `mao note` commands. > **Limit:** Cross-canvas peers are listed only when authorized within the same workspace. Screen inspection and raw terminal typing are limited to the local canvas. Source: https://trymao.dev/docs/connections-orchestration-mao-cli/peer-discovery --- # Send a task and collect its result Deliver a correlated task to a connected peer and read the result by task ID. MAO gives each delivered task a stable ID and tracks its progress. Connect the sender and recipient before sending the task. ## Send and finish a task 1. From the sender’s terminal, run `mao ask ` to send a task and wait for its result. 2. For manual delivery, run `mao send `. 3. On the recipient, run `mao next` to claim the task. 4. Return the task ID and result with `mao result `. 5. On the sender, run `mao wait ` to read a pending result. > **Note:** Task states include pending, delivered, completed, and failed. > **Limit:** Prompts and results are limited to 1 MiB. After a crash, unfinished work can be delivered again, so recipients should tolerate duplicate tasks. Source: https://trymao.dev/docs/connections-orchestration-mao-cli/task-delivery --- # Manage agents as an Orchestrator Recruit an agent, connect it to context, notify the person, or dismiss it. An Orchestrator can manage connected agents through MAO’s bridge commands. Its access is controlled separately from a regular agent terminal. ## Run an Orchestrator action 1. Recruit an agent with `mao recruit --preset --role `. 2. Use `mao connect ` to give it needed peer or note access. 3. Use `mao notify ` to notify the person, or `mao dismiss ` to dismiss an agent. 4. To let agents send notifications, enable **Allow agents to notify you** in Settings. > **Limit:** Orchestrator commands require the Orchestrator permission. Notifications are off by default and unavailable on Windows. Remote-canvas and directory recruitment are not included. Source: https://trymao.dev/docs/connections-orchestration-mao-cli/orchestrator-actions --- # Read and update a connected note Grant one terminal access to a note and use the bridge to read or append content. A terminal-to-note connection lets that terminal list, read, and append to the selected note. MAO handles the note’s storage path behind the scenes. ## Grant note access 1. Connect the terminal to the note on the canvas. 2. Run `mao note list` in the connected terminal. 3. Use `mao note read ` to read it or `mao note append ` to add text. 4. Check the note node to see the appended content. > **Note:** Appends are atomic, and open note views reconcile them with their current text. > **Limit:** Access is limited to notes explicitly connected to that terminal. Note text and an individual append are limited to 1 MiB; storage paths are not exposed. Source: https://trymao.dev/docs/connections-orchestration-mao-cli/bridge-note-access --- # Find available MAO CLI commands Use mao help to find the bridge commands available to connected agents and Orchestrators. The `mao` command exposes bridge actions for connected agents. Run `mao help` in a connected terminal to see the command syntax available there. ## Use a bridge command 1. Open a connected agent terminal. 2. Run `mao help` and choose the command for the task. 3. Run the command with the peer, note, task, or other ID it needs. 4. Use `mao check ` or `mao ask --raw ` to inspect or type into a connected local terminal. > **Note:** With arguments, `mao` runs a command. Without arguments, it opens the MAO desktop app. > **Limit:** Some commands require the **ORCHTOPUS** permission. Agents cannot delete workspaces, folders, canvases, or layers; layers can be archived. Remote runtimes are not included. Source: https://trymao.dev/docs/connections-orchestration-mao-cli/bridge-cli-surface --- # Schedule a routine Schedule a recurring prompt for an agent or a reminder for yourself. A routine runs a prompt on a schedule or reminds you at a chosen time. Open the routines view to create, pause, review, or edit routines. ## Create a routine 1. Open **Routines** from the toolbar or palette, or choose **Schedule a routine…** from an agent node’s menu. 2. Choose **+** or **New routine…**. 3. Set the target, prompt or reminder, and schedule. 4. Review the routine under **Scheduled**. Use its row menu to **Run now**, **Edit**, or **Delete**. 5. Pause a routine from its row when you want to stop scheduled runs temporarily. > **Note:** Repeating intervals must be at least 30 seconds. Reminder routines use notifications; prompt routines need a running agent. > **Limit:** Routines do not keep the computer awake for a scheduled run. Source: https://trymao.dev/docs/routines/scheduled-routines --- # Manage routines from the CLI List, create, run, edit, enable, disable, or delete routines with mao routine. The `mao routine` commands let an Orchestrator manage scheduled prompts and reminders from a connected terminal. Use `mao routine list` to see existing routines. ## Create or run a routine 1. Run `mao routine list` or `mao routine show ""` to inspect routines. 2. Create one with `mao routine create "" --command ""` and a schedule such as `--every 30m`, `--daily 09:00`, `--weekly mon,fri@09:00`, or `--once "2026-06-20 15:00"`. 3. Use `mao routine run ""` to run it now, or `mao routine edit ""` to change it. 4. Use `mao routine enable`, `mao routine disable`, or `mao routine delete` with the routine name to manage it. > **Limit:** Routine CLI commands require Orchestrator access. Duplicate names need an `--id` selector. A prompt target must be an agent session, not a shell. Source: https://trymao.dev/docs/routines/routine-cli --- # Create and edit Markdown notes Add a note node, write Markdown, and let MAO save the note locally. A note is a local Markdown file shown as a node on your canvas. Select it to edit; when you leave it unselected, its card previews the opening lines. ## Add a note 1. Choose **New note** from the canvas controls. 2. Place the note on the canvas. 3. Select it and type your Markdown content. 4. Click another node or empty canvas when you are done; MAO saves edits to the note file. > **Note:** The note editor styles Markdown as you type; it does not have separate raw and rendered modes. > **Limit:** If another process changes the same note, MAO preserves your local edits when the shared text has changed and surfaces the conflict instead of overwriting them. Source: https://trymao.dev/docs/notes-binders/markdown-notes --- # Stack notes into a binder Collect notes in a tabbed binder while keeping each note as its own item. A binder groups notes into one tabbed canvas node while preserving each note’s identity. You can create one from a selection or file notes into an existing binder. ## Create and use a binder 1. Select the notes you want to collect. 2. Choose **Stack notes into a binder** from the palette or press Ctrl + Shift + B on Windows/Linux or Cmd + Shift + B on macOS. 3. Click a tab to show that note. Use **+** to add another note. 4. Drag a note onto the binder to file it there. 5. To manage a tab, secondary-click it and choose **Rename**, **Unstack**, or **Delete**. > **Note:** Deleting a binder releases its notes onto the canvas instead of deleting them. > **Limit:** A binder created automatically from a stack disappears when emptied. A deliberately created empty binder remains. Source: https://trymao.dev/docs/notes-binders/note-binders --- # Work with connected notes from the CLI List, read, and append to notes that a terminal is explicitly connected to. A connected terminal can use MAO’s bridge to read and append to a note. The connection grants access only to that note. ## Read or append a note 1. Connect the agent terminal to the note on the canvas. 2. In that terminal, run `mao note list` to see available connected notes. 3. Run `mao note read ` to read one, or `mao note append ` to add text. 4. Refresh the open note view if needed; MAO reconciles bridge appends with the editor. > **Limit:** Notes and individual append requests are limited to 1 MiB. MAO keeps storage paths private. An edit to the shared prefix stays in the editor and is surfaced as a conflict rather than overwritten. Source: https://trymao.dev/docs/notes-binders/note-cli --- # Create a worktree layer Make an isolated Git worktree and canvas state for parallel work. A layer gives parallel work its own Git worktree and canvas state. You can create one from the navigator’s layer rail. ## Create a layer 1. Open the navigator and choose **New layer** in the layer rail. 2. Enter a layer name and branch name in the sheet. 3. If you want a starting layout, choose the option to copy the Ground layout. 4. Finish the sheet to create the layer. > **Note:** Creating a layer does not switch the canvas to it. Choose the layer in the rail when you are ready to work there. > **Limit:** Copied nodes receive new IDs and begin as drafts. Permission-bypass launch options are not copied. Source: https://trymao.dev/docs/layers-git-worktrees/create-layer --- # Set a layer status Add a short status and progress marker beneath a layer in the navigator. A layer status lets collaborators see whether work is active, blocked, under review, or done. Set it from a terminal on that layer. ## Update the status 1. Open a terminal on the layer whose status you want to change. 2. Run `mao layer status` with a state, for example `mao layer status --state review`. 3. Add a progress fraction with `--progress 3/5` if useful, or use `--clear` to remove the status. 4. Reopen the navigator to see the status beneath the layer. > **Note:** Available states are `working`, `blocked`, `review`, and `done`. You can include a one-line status message. > **Limit:** Changing another layer’s status requires Orchestrator access. `blocked` and `review` mark the layer as needing attention. Source: https://trymao.dev/docs/layers-git-worktrees/layer-status --- # Land a layer into Ground Check a layer and merge or fast-forward its branch into Ground. Landing brings a layer’s Git branch into Ground after MAO checks the worktree and destination. Review the checks before confirming the change. ## Land a layer 1. Switch to Ground. 2. Open the layer row menu and choose **Land…**, or choose **Land layer: …** from the palette. 3. Review the checks and destination branch in the landing sheet. 4. Enable **Keep the layer** only if you want to keep it after landing. 5. Choose **Land** to proceed. > **Note:** An Orchestrator can use `mao layer land ""` from Ground. > **Limit:** MAO checks for conflicts and uncommitted changes first. By default the layer is archived after landing. Source: https://trymao.dev/docs/layers-git-worktrees/land-layer --- # Archive and restore a layer Archive a layer that you no longer need in the rail and restore it later. Archiving removes a layer from the active rail while keeping its worktree available to restore. MAO protects active or unsaved work before it archives a layer. ## Archive or restore 1. Open the layer’s row menu in the navigator. 2. Choose **Archive**. 3. If MAO reports an active terminal or unsaved changes, save the changes before continuing. 4. To bring the layer back, open the archived layers list and choose **Restore** on its row. > **Note:** An Orchestrator can use `mao layer archive ""` or `mao layer restore ""`. > **Limit:** Archiving is reversible; there is no layer delete command. Source: https://trymao.dev/docs/layers-git-worktrees/archive-restore-layer --- # Switch between layers Move between Ground and its worktree layers from the navigator rail. The navigator’s layer rail switches between Ground and isolated layers. Switching changes the active canvas and worktree; it does not merge branches. ## Change the active layer 1. Open the navigator’s layer rail and choose the layer you want. 2. To move keyboard focus back to the rail, press Ctrl + Up on Windows/Linux or Cmd + Up on macOS. 3. To switch to the previous layer, press Ctrl + Shift + Up on Windows/Linux or Cmd + Shift + Up on macOS. > **Note:** Use the landing action to bring changes into Ground; switching layers alone leaves their branches separate. Source: https://trymao.dev/docs/layers-git-worktrees/switch-layers --- # Browse project files Open a project file tree and select regular files to view or edit. A file tree node browses files beneath the project root. Expand folders to find a file, then select a regular file to open it. ## Browse the tree 1. Choose **New file tree** and place the node on the canvas. 2. Expand a folder to browse its contents. 3. Choose **Refresh** to reload the listing. 4. Select a regular file to open it in a project file editor. > **Limit:** The tree stays inside the project root, cannot be connected to an agent, and shows at most 5,000 entries. Source: https://trymao.dev/docs/files-editor-git-changes/file-tree --- # Edit a project file Open a project file as plain text and let MAO save your edits. The project file editor opens safe UTF-8 files as plain text and saves edits automatically. Select a file in a file tree to create its editor node. ## Open and edit a file 1. Add a **New file tree** node and browse to the file. 2. Select a regular file to open its editor node. 3. Type your changes; MAO autosaves them. 4. Choose the Git status chip on the editor to show or hide its diff. > **Note:** If the file changes outside MAO, the editor detects that change before saving over it. > **Limit:** Files are limited to 1 MiB. MAO refuses symlinks and paths outside the project root. The editor has no syntax highlighting, search, or diagnostics. Source: https://trymao.dev/docs/files-editor-git-changes/project-file-editor --- # Review and stage a file diff Inspect an edited file’s Git diff and stage or unstage it from the editor. A project file editor can show the Git changes for its file. Stage or unstage the file after reviewing the displayed diff. ## Review a file 1. Open a file in the project file editor. 2. Choose its Git status chip to show the diff. 3. Review the staged and unstaged changes. 4. Choose **Stage** or **Unstage** as needed. > **Note:** MAO saves the latest editor content before staging the file. > **Limit:** The diff is limited to 512 KiB and 2,000 displayed lines. Untracked files show their status without a generated diff. Source: https://trymao.dev/docs/files-editor-git-changes/file-git-diff --- # Review repository changes Browse staged, unstaged, and other repository changes in one live view. The repository changes view shows Git status across the project. Use its tabs and file actions to review and stage changes. ## Open the changes view 1. Choose **Git repository status** from the toolbar or command palette. 2. Choose **All**, **Changes**, or **Staged** to filter the list. 3. Type in **Filter files** to find a path. Use **Stage all** or **Unstage all** when appropriate. 4. Open **More** for **Hide whitespace**, **Expand all files**, **Collapse all files**, **Refresh**, and **Copy git diff command**. 5. Open a file or hunk menu to stage, unstage, or restore that change. > **Limit:** This view reads live repository state and is not saved in canvas JSON. It displays at most 2 MiB or 5,000 entries. Restore actions ask before changing files and refuse unsafe operations. Source: https://trymao.dev/docs/files-editor-git-changes/repository-changes --- # Compare unified and split diffs Choose a side-by-side or unified view for a Git diff. The changes view can display a diff side by side or as one unified column. The layout adapts to the available width. ## Change the diff layout 1. Open **Git repository status** and select a changed file. 2. Use the **Split** or **Unified** toolbar toggle. 3. In a narrow node, choose **Files** to show the hidden file tree. > **Note:** MAO adapts the layout to the node width; narrow views hide the file tree behind **Files**. Source: https://trymao.dev/docs/files-editor-git-changes/diff-layout --- # Browse recent Git history Review recent commits and read their metadata, stats, and patches. The repository changes panel includes a read-only history view. Select a commit to see its details and patch. ## View a commit 1. Open **Git repository status**. 2. Choose **History**. 3. Select a commit to view its metadata, change summary, and patch. > **Limit:** The history list shows up to 200 commits. Commit details are read-only; branch labels and a commit graph are not included. Source: https://trymao.dev/docs/files-editor-git-changes/git-history --- # Open a browser portal Place an embedded Chromium browser on the canvas and use its navigation controls. A browser portal places an external Chromium window on the canvas. You can browse from its address bar and connect an agent when you want it to inspect or control the page. ## Browse in a portal 1. Choose **New portal** and place it on the canvas. 2. Enter a URL in the address bar. 3. Use **Back**, **Forward**, **Reload**, **New tab**, and the tab controls to navigate. 4. On Windows/Linux, use Ctrl + L, Ctrl + T, Ctrl + R, or Ctrl + W. On macOS, use Cmd with each key. 5. Navigate back or forward with Alt + Left/Right on Windows/Linux, or Option + Left/Right on macOS. > **Note:** Connect an agent terminal to the portal before using `mao portal` commands. > **Limit:** Only the active tab is durable when reopened. Browser profile data, popups, and downloads are not included in this stage. Source: https://trymao.dev/docs/portals-browser-android-ios/browser-portal --- # Let an agent drive an authorized browser Use mao portal commands to inspect and interact with a browser connected to an agent. A connected agent can inspect and interact with a live browser portal through the MAO bridge. The terminal must be connected to that portal. ## Drive a connected portal 1. Connect the agent terminal to the browser portal. 2. Run `mao portal navigate ` to open a page. 3. Use `mao portal info`, `screenshot`, or `snapshot` to inspect it. 4. Use `click`, `fill`, `type`, `key`, `scroll`, `text`, or `evaluate` for the interaction you need. 5. Run `mao portal close ` when you are done. > **Limit:** Each operation checks the connection. These commands control an existing live portal; they do not launch a browser by themselves. Source: https://trymao.dev/docs/portals-browser-android-ios/browser-portal-cli --- # Control an Android device portal Connect an Android emulator or attached device and interact with it from the canvas. An Android device portal shows an emulator or attached device as a canvas node. You can use its controls yourself or connect an agent to run device commands. ## Open an Android device 1. Choose **New device portal** and place it on the canvas. 2. Select a listed Android device or runtime in the setup sheet. 3. Connect an agent terminal if it needs to inspect or control the device. 4. Use `mao portal info`, `screenshot`, or `snapshot` to inspect the screen. Commands such as `click`, `swipe`, `type`, `button`, `launch`, `terminate`, `boot`, and `shutdown` control the device. > **Limit:** MAO needs Android SDK tools or an attached device to list a target. Device frames stream while the portal is painted; an off-screen or collapsed portal stops streaming. Source: https://trymao.dev/docs/portals-browser-android-ios/android-device-portal --- # View an iOS Simulator portal Add an existing macOS iOS Simulator to the canvas and connect an agent to it. An iOS Simulator portal connects an existing simulator to the canvas. You can view and drive it from the portal or give a connected agent access. ## Add a simulator 1. On macOS, choose **New device portal** and place it on the canvas. 2. Select an available iOS Simulator in the setup sheet. 3. Connect an agent terminal if it needs to inspect or control the simulator. 4. Use the portal controls or `mao portal` device commands to interact with the simulator. > **Limit:** This feature is macOS-only. Create and delete simulator devices in Xcode; MAO lists existing simulators. The portal streams only while its view is painted. Source: https://trymao.dev/docs/portals-browser-android-ios/ios-simulator-portal --- # Save a canvas arrangement Save selected nodes and their internal connections as a reusable layout. An arrangement stores a reusable group of canvas nodes and the connections between them. Save a selection or save the current canvas as a starting layout. ## Save an arrangement 1. Select at least two nodes. 2. Choose **Save arrangement…** from the palette, canvas overflow menu, or arrangement library. 3. Name the arrangement and save it. 4. To save the whole canvas, use the same action with fewer than two nodes selected. 5. Open the arrangement library later to search or filter saved layouts. > **Limit:** Saving arrangements is unavailable during the trial. Arrangements omit node locks, permission-bypass settings, prompt drafts, provider sessions, and credentials. Source: https://trymao.dev/docs/arrangements/saved-arrangements --- # Apply a saved arrangement Place a saved group of nodes and connections onto the current canvas. Applying an arrangement stamps its saved nodes and internal connections onto the current canvas. Agent nodes arrive as drafts so you can decide when to start them. ## Place an arrangement 1. Open the arrangement library and find the layout you want. 2. Drag its card onto the canvas, double-click the card, or select it and press Enter. 3. Position the arrangement where you want it. 4. Review the new nodes and connections; start any agent nodes when you are ready. > **Note:** You can also apply an arrangement from the multi-selection bar or command palette. > **Limit:** Provider sessions and other private provider state are not copied. Agent nodes are drafts until you start them. Source: https://trymao.dev/docs/arrangements/apply-arrangements --- # Group nodes Move a selection of connected canvas nodes together as a group. A canvas group lets you move several nodes as one unit. Grouping affects layout only; it does not change which peers an agent can access. ## Group a selection 1. Select the nodes you want to move together. 2. Choose **Group** in the selection toolbar or command palette. 3. Drag a grouped node to move the group. 4. Choose **Ungroup** in the toolbar or palette when you want to move nodes separately. > **Note:** Grouping one selected node also includes nodes connected to it. > **Limit:** A group does not change orchestration access or the permissions granted by node connections. Source: https://trymao.dev/docs/groups-drawing/node-groups --- # Draw a rectangle Add a resizable rectangle to mark an area of the canvas. Rectangles are canvas annotations for outlining an area or grouping related work visually. They are drawing objects, not nodes. ## Add a rectangle 1. Choose **Rectangle** under **Draw and more**, or press R while the canvas has focus. 2. Drag across the canvas to draw the rectangle. 3. Press Escape to return to the Select tool. > **Limit:** Drawings cannot be connection endpoints. Source: https://trymao.dev/docs/groups-drawing/rectangle-drawing --- # Sketch with Pen Draw a freehand stroke directly on the canvas. Use Pen to add a freehand annotation to the canvas. Each stroke stays a drawing object and cannot connect to an agent or note. ## Draw a stroke 1. Choose **Pen** under **Draw and more**, or press P with the canvas focused. 2. Drag across the canvas to sketch. 3. Press Escape to return to the Select tool. > **Limit:** A stroke is limited to 2,048 points and is not a connection endpoint. Source: https://trymao.dev/docs/groups-drawing/free-drawing --- # Place labels and text blocks Add a short label or editable text block to explain part of the canvas. Labels and text blocks annotate the canvas without changing node behavior. Place one near the work it describes and edit its text when needed. ## Add a label or text block 1. Choose **Label** or **Text** from **Draw and more**. 2. Or press L for Label or T for Text when the canvas has focus. 3. Place the object on the canvas. 4. Select it and press Enter to edit its text. > **Limit:** Text content is limited to 32 KiB. Labels and text drawings cannot connect to agents. Source: https://trymao.dev/docs/groups-drawing/labels-and-text --- # Switch canvas drawing tools Choose Select, Rectangle, Pen, Label, or Text from the tool rail or keyboard. The tool rail groups drawing actions under **Draw and more**. With the canvas focused, you can also select a tool with its shortcut. ## Choose a tool 1. Press V for Select, R for Rectangle, P for Pen, L for Label, or T for Text. 2. Or open **Draw and more** on the rail and choose a tool. 3. Press Escape to return to Select. > **Limit:** Tool shortcuts work only when the canvas owns focus. Terminals and text inputs receive their own keys. Source: https://trymao.dev/docs/groups-drawing/drawing-toolbar