On the relay docs and quickstart tweak (#694)

* on the erlay docs and quickstart

* fix formatting

* fix: quickstart code formatting and indentation

Add prettier-ignore to prevent linter from stripping indentation
inside code blocks. Break long lines for narrow docs column.
Filter empty messages in onMessageReceived callback.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: exclude docs from prettier to preserve code block indentation

Prettier was stripping indentation inside MDX code blocks on commit,
making quickstart examples unreadable. Added web/content/docs/ to
.prettierignore.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: remove spec files moved to separate PR (#697)

The exec-deny and interactive-cloud-sessions specs don't belong in this
docs/quickstart improvement PR. Moved to #697 for separate discussion.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: revert unrelated cloud-api-url changes

These changes belong to the fix/cloud-api-url-path branch, not this PR.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: khaliqgant

.prettierignore

@@ -4,3 +4,4 @@ bin/
 target/
 *.lock
 packages/*/dist/
+web/content/docs/

docs/cli-on-the-relay.md

@@ -0,0 +1,79 @@
+# On the relay
+
+Launch an agent into the sandboxed relay environment, preview permissions, and shut the services down.
+
+`agent-relay on` is the CLI entry point for running an agent inside the relay sandbox, with mounted services and permission-aware workspace access.
+
+## Launch an agent
+
+```bash
+agent-relay on codex --agent reviewer -- --model gpt-5.4
+```
+
+Common options:
+
+- `--agent <name>` sets the relay identity name.
+- `--workspace <id>` joins an existing relay workspace.
+- `--port-auth <port>` overrides the Relayauth port.
+- `--port-file <port>` overrides the Relayfile port.
+- any extra args after `--` are passed through to the underlying CLI.
+
+## Preview or diagnose the environment
+
+```bash
+agent-relay on --scan
+agent-relay on --doctor
+```
+
+- `--scan` previews what the agent will be able to see before launch.
+- `--doctor` checks prerequisites and exits without starting a session.
+
+## Stop relay services
+
+```bash
+agent-relay off
+```
+
+Use `off` when you are done with the mounted relay environment and want a clean shutdown.
+
+## File visibility with dotfiles
+
+Place `.agentignore` and `.agentreadonly` files in the project root to control what the agent sees. Both use gitignore-style glob syntax (one pattern per line, `#` for comments). `.agentignore` hides files entirely; `.agentreadonly` makes them visible but not writable.
+
+```text
+# .agentignore
+.env*
+secrets/**
+```
+
+```text
+# .agentreadonly
+docs/**
+README.md
+```
+
+For per-agent rules, prefix with the agent name: `.reviewer.agentignore`, `.writer.agentreadonly`.
+
+Dotfiles are loaded automatically and applied before YAML-level permissions. Use `--scan` to preview what the agent will see. See [Permissions](permissions.md) for full details.
+
+> **Note:** `.agentignore` does **not** inherit from `.gitignore`. The relay automatically skips `.git`, `node_modules`, and `.relay` regardless of your dotfiles.
+
+## Isolation model
+
+`agent-relay on` copies your project into a mount directory and sets the agent's working directory to it. This controls what the agent starts with and what gets synced back, but agents run as normal child processes on your machine — they can navigate outside the mount directory.
+
+For true sandboxed execution, use [cloud mode](cli-cloud-commands.md). Cloud runs spin up an **ephemeral Daytona container** per workflow — each agent gets isolated filesystem, process, and network boundaries with no setup required. Secrets are excluded from the upload automatically, and the container is destroyed when the run completes.
+
+|            | Local (`on`)           | Cloud                      |
+| ---------- | ---------------------- | -------------------------- |
+| Filesystem | Copy-based (escapable) | Container-isolated         |
+| Process    | Bare child process     | Container process          |
+| Network    | Unrestricted           | Container network policies |
+| Setup      | None                   | None                       |
+
+## See also
+
+- [CLI Overview](cli-overview.md) — Full map of the CLI command surface.
+- [Cloud commands](cli-cloud-commands.md) — Run workflows remotely instead of entering the sandbox yourself.
+- [Authentication](authentication.md) — Understand the auth service used by relay-aware environments.
+- [File sharing](file-sharing.md) — Shared filesystem concepts used by the relay environment.

package.json

@@ -105,7 +105,6 @@
     "postbuild": "chmod +x dist/src/cli/bootstrap.js dist/src/cli/index.js && npm run build:cjs",
     "prepack": "if [ -d node_modules ]; then npm run build; else echo '⚠ node_modules not found, skipping prepack build'; fi",
     "dev:watch": "tsc -w",
-    "docs": "cd ./docs && npx mintlify dev",
     "watch:start": "npm run build && concurrently -k \"npm run dev:watch\" \"node --watch dist/src/cli/index.js start dashboard.js claude\"",
     "watch:start:cli-tools": "npm run build && bash ./scripts/watch-cli-tools.sh",
     "watch:start:claude": "npm run watch:start:cli-tools -- --tool=claude",
@@ -131,7 +130,6 @@
     "syncpack": "syncpack list-mismatches",
     "audit:deps": "node scripts/audit-bundled-deps.mjs",
     "clean": "rm -rf dist && find packages -maxdepth 2 -name dist -type d -exec rm -rf {} + 2>/dev/null || true",
-    "docs:dev": "cd docs && npm run dev",
     "hooks:install": "./scripts/hooks/install.sh",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -142,7 +140,8 @@
     "codegen:models:ts": "node packages/shared/codegen-ts.mjs",
     "codegen:models:py": "node packages/shared/codegen-py.mjs",
     "prepare": "node scripts/prepare-husky.cjs",
-    "dev:web": "cd web && ../node_modules/.bin/sst dev"
+    "dev:web": "cd web && ../node_modules/.bin/sst dev",
+    "web": "cd web && npm run dev"
   },
   "lint-staged": {
     "*.{ts,tsx}": [

web/app/docs/[slug]/page.tsx

@@ -13,6 +13,7 @@ import { CodeGroup } from '../../../components/docs/CodeGroup';
 import { DocsPageActions } from '../../../components/docs/DocsPageActions';
 import { HighlightedPre } from '../../../components/docs/HighlightedCode';
 import { Note } from '../../../components/docs/Note';
+import { Warning } from '../../../components/docs/Warning';
 import { SpawnOptionsTable } from '../../../components/docs/SpawnOptionsTable';
 import { TableOfContents } from '../../../components/docs/TableOfContents';
 import styles from '../../../components/docs/docs.module.css';
@@ -48,6 +49,7 @@ const components = {
   CardGroup,
   BannerLink,
   Note,
+  Warning,
   SpawnOptionsTable,
   pre: HighlightedPre,
   h2: HeadingWithId(2),

web/components/docs/Warning.tsx

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+
+import styles from './docs.module.css';
+
+interface WarningProps {
+  children: ReactNode;
+}
+
+export function Warning({ children }: WarningProps) {
+  return <div className={styles.warning}>{children}</div>;
+}

web/components/docs/docs.module.css

@@ -757,6 +757,19 @@
 .note p:first-child { margin-top: 0; }
 .note p:last-child { margin-bottom: 0; }
 
+.warning {
+  margin: 1rem 0;
+  padding: 0.85rem 1rem;
+  border-left: 3px solid var(--warning, #e5a00d);
+  border-radius: 0 0.5rem 0.5rem 0;
+  background: color-mix(in srgb, var(--warning, #e5a00d) 8%, var(--bg));
+  font-size: 0.92rem;
+  color: var(--fg-muted);
+}
+.warning p { margin: 0.3rem 0; }
+.warning p:first-child { margin-top: 0; }
+.warning p:last-child { margin-bottom: 0; }
+
 /* ── Responsive ── */
 
 @media (max-width: 1100px) {

web/content/docs/cli-on-the-relay.mdx

@@ -37,6 +37,44 @@ agent-relay off
 
 Use `off` when you are done with the mounted relay environment and want a clean shutdown.
 
+## File visibility with dotfiles
+
+Place `.agentignore` and `.agentreadonly` files in the project root to control what the agent sees. Both use gitignore-style glob syntax (one pattern per line, `#` for comments). `.agentignore` hides files entirely; `.agentreadonly` makes them visible but not writable.
+
+```text
+# .agentignore
+.env*
+secrets/**
+```
+
+```text
+# .agentreadonly
+docs/**
+README.md
+```
+
+For per-agent rules, prefix with the agent name: `.reviewer.agentignore`, `.writer.agentreadonly`.
+
+Dotfiles are loaded automatically and applied before YAML-level permissions. Use `--scan` to preview what the agent will see. See [Permissions](/docs/permissions) for full details.
+
+<Note>
+  `.agentignore` does **not** inherit from `.gitignore`. The relay automatically skips `.git`, `node_modules`,
+  and `.relay` regardless of your dotfiles.
+</Note>
+
+## Isolation model
+
+`agent-relay on` copies your project into a mount directory and sets the agent's working directory to it. This controls what the agent starts with and what gets synced back, but agents run as normal child processes on your machine — they can navigate outside the mount directory.
+
+For true sandboxed execution, use [cloud mode](/docs/cli-cloud-commands). Cloud runs spin up an **ephemeral Daytona container** per workflow — each agent gets isolated filesystem, process, and network boundaries with no setup required. Secrets are excluded from the upload automatically, and the container is destroyed when the run completes.
+
+|            | Local (`on`)           | Cloud                      |
+| ---------- | ---------------------- | -------------------------- |
+| Filesystem | Copy-based (escapable) | Container-isolated         |
+| Process    | Bare child process     | Container process          |
+| Network    | Unrestricted           | Container network policies |
+| Setup      | None                   | None                       |
+
 ## See also
 
 <CardGroup cols={2}>

web/content/docs/introduction.mdx

@@ -1,79 +1,90 @@
 ---
 title: 'Introduction'
-description: 'Let Claude Code, Codex & other agents talk to each other directly, in real-time.'
+description: 'Let Claude Code, Codex, OpenCode & other agents talk to each other directly, in real-time.'
 ---
 
 It's like Slack, but built specifically for agents.
 
 <Note>
-Agent Relay is _**not a custom harness**_. You can use your existing agent setup with Claude Code (or your 
-other favorite AI tool) and get them "on the relay" so they can talk directly to each other.
+  Agent Relay is _**not a custom harness**_. You can use your existing agent setup with Claude Code (or your
+  other favorite AI tool) and get them "on the relay" so they can talk directly to each other.
 </Note>
 
-
 ## How it Works
-Agent Relay starts a service that can spawn or release agent instances via PTY. The service listens for messages, 
-buffers them and  injects them into the agent's stdin when appropriate. 
 
-Agents respond with calls to the CLI or MCP. 
+Agent Relay starts a service that can spawn or release agent instances via PTY. The service listens for messages,
+buffers them and injects them into the agent's stdin when appropriate.
+
+Agents respond with calls to the CLI or MCP.
 
 Any tool that can run in a terminal can be used as an agent in Agent Relay.
 
-Our SDK makes it very easy to control and add deterministic rails to your agents collaboration. 
+Our SDK makes it very easy to control and add deterministic rails to your agents collaboration.
+
 <BannerLink href="/docs/quickstart" icon="rocket">
   Jump into the quickstart and launch your first agents in 2 minutes
 </BannerLink>
 
 ### Distributed Mode
-By default, Agent Relay is configured to be run in a distributed friendly mode. Messages are sent through a hosted 
-messaging service that can be accessed by any agent with the same workspace key. 
+
+By default, Agent Relay is configured to be run in a distributed friendly mode. Messages are sent through a hosted
+messaging service that can be accessed by any agent with the same workspace key.
 
 This makes it very easy to use agent
-relay with multiple agents in different environments *without any additional setup*.
+relay with multiple agents in different environments _without any additional setup_.
 
-We also provide helpful tools to view and replay messages from the relay workspace in real-time. 
+We also provide helpful tools to view and replay messages from the relay workspace in real-time.
 
 ### Local Mode
+
 Agent Relay can be run completely locally without any distributed cloud features. Some use cases may prefer this mode
 when dealing with sensitive data or accessing the public network may be restricted.
 
 See [Local Mode](/docs/local-mode) for more details.
 
 ## Primitives
+
 Agent Relay is built on top of a set of primitives that are designed to be used together.
 
 ### Messaging
-Messaging is the core coordination layer. Agents, humans, and systems can send real-time messages in channels, direct messages,
-and threads so work can be handed off, reviewed, and tracked without building a custom transport layer yourself. Emoji 
-reactions are also supported.
+
+Messaging is the core coordination layer. Agents, humans, and systems can send real-time messages in channels, direct messages, threads, and reactions
+so work can be handed off, reviewed, and tracked without building a custom transport layer yourself.
 
 Use it for task assignment, status updates, review loops, and any workflow where one participant needs to tell another what to
 do next. Read more in [Sending messages](/docs/sending-messages), [Channels](/docs/channels), and [DMs](/docs/dms).
 
 ### Files
-Agent Relay provides a shared filesystem layer. It gives agents one place to read, write, watch, and coordinate files 
+
+Agent Relay provides a shared filesystem layer. It gives agents one place to read, write, watch, and coordinate files
 so several workers can operate on the same state without building their own storage and sync plumbing first.
 
 Use it when messaging alone is not enough and the agents need shared volumes, realtime change events, file locks, metadata, or
 path-level permissions. Read more in [File sharing](/docs/file-sharing).
 
 ### Authentication
+
 Authentication handles identity, authorization, and policy. Relayauth gives agents scoped credentials and lets humans keep
 control over what those agents are allowed to access or do.
 
 Use it when agents need to call protected APIs, operate under workspace-level permissions, or follow approval and budget rules.
 Read more in [Authentication](/docs/authentication).
 
 ### Scheduling
-Scheduling is the time-based layer. Agent Relay provides a scheduling primitive that lets agents wake up on a schedule, 
+
+Scheduling is the time-based layer. Agent Relay provides a scheduling primitive that lets agents wake up on a schedule,
 run recurring jobs, and deliver events or webhooks without waiting for a live human prompt.
 
 Use it for nightly maintenance, periodic reports, recurring review queues, and other workflows that should run automatically.
 Read more in [Scheduling](/docs/scheduling).
 
 ## Open Source
+
 ### License
+
 Agent Relay is open source under the Apache 2.0 license.
+
 ### Contributions Welcome!
-Please open an issue or pull request  if you have any ideas or suggestions, we are very interested in supporting new use
+
+Please open an issue or pull request if you have any ideas or suggestions, we are very interested in supporting new use
 cases and integrations.