auvrynt 1.0.2 → 1.0.5

package/docs/chatgpt-coding-workflow.md

@@ -1,143 +1,143 @@
-# ChatGPT Coding Workflow
-
-Auvrynt brings a Codex-style coding-agent loop to ChatGPT and other MCP hosts:
-inspect the repo, follow local instructions, make scoped edits, run
-verification, and show the user what changed.
-
-## Open One Workspace
-
-ChatGPT should call `open_workspace` once for a project folder:
-
-```json
-{
-  "path": "~/work/my-project"
-}
-```
-
-The result includes a `workspaceId`. All later file, search, edit, show-changes,
-and shell calls should reuse that same `workspaceId`.
-
-Do not reopen the same folder unless:
-
-- the `workspaceId` is rejected as unknown
-- the user switches to another folder
-- the user switches between checkout and worktree mode
-- the user explicitly asks to reopen
-
-## Checkout Mode
-
-Checkout mode is the default. Auvrynt opens the actual directory:
-
-```json
-{
-  "path": "~/work/my-project"
-}
-```
-
-Use this when the user wants ChatGPT to work in the current checkout.
-
-## Worktree Mode
-
-Use worktree mode for isolated parallel work:
-
-```json
-{
-  "path": "~/work/my-project",
-  "mode": "worktree"
-}
-```
-
-Managed worktrees are created under:
-
-```text
-~/.auvrynt/worktrees
-```
-
-Worktree mode requires a Git repository with at least one commit. It starts from
-`HEAD` unless `baseRef` is provided.
-
-Uncommitted source checkout changes are not copied into the managed worktree.
-Auvrynt reports when the source checkout was dirty so the model can decide how
-to proceed with the user.
-
-## Project Instructions
-
-When a workspace opens, Auvrynt loads root-level instruction files:
-
-- `AGENTS.md`
-- `AGENTS.MD`
-- `CLAUDE.md`
-- `CLAUDE.MD`
-
-Nested instruction files are returned as `availableAgentsFiles`. The model
-should read the relevant nested file before working under that directory.
-
-This keeps instructions explicit and inspectable instead of silently injecting
-new context during later tool calls.
-
-## Skills
-
-Skills are enabled by default for coding-agent workflows.
-
-Auvrynt discovers skills from:
-
-- `AUVRYNT_AGENT_DIR`, which defaults to `~/.codex`
-- project `.pi/skills`
-- optional paths from `AUVRYNT_SKILL_PATHS`
-
-When `open_workspace` returns matching skills, the model should read the
-advertised `SKILL.md` before following that skill.
-
-Skill paths may be outside the workspace. Auvrynt only permits reading:
-
-- advertised `SKILL.md` files
-- files under a skill directory after that skill's `SKILL.md` has been read
-
-Set `AUVRYNT_SKILLS=0` to hide skills from workspace output.
-
-## Tool Names
-
-Short names are the default:
-
-- `open_workspace`
-- `read`
-- `write`
-- `edit`
-- `bash`
-
-By default, Auvrynt also runs in `AUVRYNT_TOOL_MODE=minimal`, so dedicated
-`grep`, `glob`, and `ls` tools are hidden. Use `bash` with command-line tools
-such as `rg`, `find`, and `ls` for search and directory inspection.
-
-Legacy names are available with `AUVRYNT_TOOL_NAMING=legacy`:
-
-- `open_workspace`
-- `read_file`
-- `write_file`
-- `edit_file`
-- `run_shell`
-
-Use `AUVRYNT_TOOL_MODE=full` to restore dedicated search and directory tools.
-
-## Show Changes
-
-By default, `AUVRYNT_WIDGETS=full`.
-
-In that mode, Auvrynt attaches widget UI to the exposed workspace, file, edit,
-and shell tools. The aggregate `show_changes` tool is not exposed by default.
-
-Use `AUVRYNT_WIDGETS=off` to disable widget UI, or `AUVRYNT_WIDGETS=changes`
-to expose the aggregate show-changes flow.
-
-## Shell Use
-
-The shell tool is for commands that belong in a terminal:
-
-- tests
-- builds
-- git inspection
-- package scripts
-- environment checks
-
-File writes should go through the edit/write tools rather than shell
-redirection, heredocs, `tee`, `sed -i`, or generated scripts.
+# ChatGPT Coding Workflow
+
+Auvrynt brings a Codex-style coding-agent loop to ChatGPT and other MCP hosts:
+inspect the repo, follow local instructions, make scoped edits, run
+verification, and show the user what changed.
+
+## Open One Workspace
+
+ChatGPT should call `open_workspace` once for a project folder:
+
+```json
+{
+  "path": "~/work/my-project"
+}
+```
+
+The result includes a `workspaceId`. All later file, search, edit, show-changes,
+and shell calls should reuse that same `workspaceId`.
+
+Do not reopen the same folder unless:
+
+- the `workspaceId` is rejected as unknown
+- the user switches to another folder
+- the user switches between checkout and worktree mode
+- the user explicitly asks to reopen
+
+## Checkout Mode
+
+Checkout mode is the default. Auvrynt opens the actual directory:
+
+```json
+{
+  "path": "~/work/my-project"
+}
+```
+
+Use this when the user wants ChatGPT to work in the current checkout.
+
+## Worktree Mode
+
+Use worktree mode for isolated parallel work:
+
+```json
+{
+  "path": "~/work/my-project",
+  "mode": "worktree"
+}
+```
+
+Managed worktrees are created under:
+
+```text
+~/.auvrynt/worktrees
+```
+
+Worktree mode requires a Git repository with at least one commit. It starts from
+`HEAD` unless `baseRef` is provided.
+
+Uncommitted source checkout changes are not copied into the managed worktree.
+Auvrynt reports when the source checkout was dirty so the model can decide how
+to proceed with the user.
+
+## Project Instructions
+
+When a workspace opens, Auvrynt loads root-level instruction files:
+
+- `AGENTS.md`
+- `AGENTS.MD`
+- `CLAUDE.md`
+- `CLAUDE.MD`
+
+Nested instruction files are returned as `availableAgentsFiles`. The model
+should read the relevant nested file before working under that directory.
+
+This keeps instructions explicit and inspectable instead of silently injecting
+new context during later tool calls.
+
+## Skills
+
+Skills are enabled by default for coding-agent workflows.
+
+Auvrynt discovers skills from:
+
+- `AUVRYNT_AGENT_DIR`, which defaults to `~/.codex`
+- project `.pi/skills`
+- optional paths from `AUVRYNT_SKILL_PATHS`
+
+When `open_workspace` returns matching skills, the model should read the
+advertised `SKILL.md` before following that skill.
+
+Skill paths may be outside the workspace. Auvrynt only permits reading:
+
+- advertised `SKILL.md` files
+- files under a skill directory after that skill's `SKILL.md` has been read
+
+Set `AUVRYNT_SKILLS=0` to hide skills from workspace output.
+
+## Tool Names
+
+Short names are the default:
+
+- `open_workspace`
+- `read`
+- `write`
+- `edit`
+- `bash`
+
+By default, Auvrynt also runs in `AUVRYNT_TOOL_MODE=minimal`, so dedicated
+`grep`, `glob`, and `ls` tools are hidden. Use `bash` with command-line tools
+such as `rg`, `find`, and `ls` for search and directory inspection.
+
+Legacy names are available with `AUVRYNT_TOOL_NAMING=legacy`:
+
+- `open_workspace`
+- `read_file`
+- `write_file`
+- `edit_file`
+- `run_shell`
+
+Use `AUVRYNT_TOOL_MODE=full` to restore dedicated search and directory tools.
+
+## Show Changes
+
+By default, `AUVRYNT_WIDGETS=full`.
+
+In that mode, Auvrynt attaches widget UI to the exposed workspace, file, edit,
+and shell tools. The aggregate `show_changes` tool is not exposed by default.
+
+Use `AUVRYNT_WIDGETS=off` to disable widget UI, or `AUVRYNT_WIDGETS=changes`
+to expose the aggregate show-changes flow.
+
+## Shell Use
+
+The shell tool is for commands that belong in a terminal:
+
+- tests
+- builds
+- git inspection
+- package scripts
+- environment checks
+
+File writes should go through the edit/write tools rather than shell
+redirection, heredocs, `tee`, `sed -i`, or generated scripts.

package/docs/configuration.md

@@ -1,132 +1,164 @@
-# Configuration Reference
-
-Auvrynt can be configured through `auvrynt init`, persisted config files, or
-environment variables.
-
-The default files are:
-
-```text
-~/.auvrynt/config.json
-~/.auvrynt/auth.json
-```
-
-Use another config directory with:
-
-```bash
+# Configuration Reference
+
+Auvrynt can be configured through `auvrynt init`, persisted config files, or
+environment variables.
+
+The default files are:
+
+```text
+~/.auvrynt/config.json
+~/.auvrynt/auth.json
+```
+
+Use another config directory with:
+
+```bash
 AUVRYNT_CONFIG_DIR=/path/to/config npx auvrynt start
-```
-
-## Commands
-
-```bash
+```
+
+## Commands
+
+```bash
 npx auvrynt init
 npx auvrynt start
 npx auvrynt doctor
 npx auvrynt config get
 npx auvrynt config set publicBaseUrl https://auvrynt.example.com
-```
-
-## Core Environment Variables
-
-| Variable | Purpose |
-| --- | --- |
-| `HOST` | Local bind host. Defaults to `127.0.0.1`. |
-| `PORT` | Local port. Defaults to `49321`. |
-| `AUVRYNT_ALLOWED_ROOTS` | Comma-separated local roots that workspaces may open. |
-| `AUVRYNT_PUBLIC_BASE_URL` | Public origin for the server, without `/mcp`. |
-| `AUVRYNT_ALLOWED_HOSTS` | Optional Host header allowlist override. |
-| `AUVRYNT_OAUTH_OWNER_TOKEN` | Owner password for OAuth approval. Must be at least 16 characters. |
-| `AUVRYNT_WORKTREE_ROOT` | Directory for managed Git worktrees. Defaults to `~/.auvrynt/worktrees`. |
-| `AUVRYNT_STATE_DIR` | Directory for SQLite state. Defaults to `~/.local/share/auvrynt`. |
-
-## OAuth
-
-Auvrynt uses a single-user OAuth approval flow.
-
-| Variable | Default |
-| --- | --- |
-| `AUVRYNT_OAUTH_ACCESS_TOKEN_TTL_SECONDS` | `3600` |
-| `AUVRYNT_OAUTH_REFRESH_TOKEN_TTL_SECONDS` | `2592000` |
-| `AUVRYNT_OAUTH_SCOPES` | `auvrynt` |
-| `AUVRYNT_OAUTH_ALLOWED_REDIRECT_HOSTS` | `chatgpt.com,localhost,127.0.0.1` |
-
-MCP clients discover metadata from:
-
-```text
-/.well-known/oauth-protected-resource/mcp
-/.well-known/oauth-authorization-server
-```
-
-## Tool Modes
-
-`AUVRYNT_TOOL_NAMING` controls tool names.
-
-| Value | Behavior |
-| --- | --- |
-| `short` | Default. Uses `read`, `edit`, `bash`, and related names. |
-| `legacy` | Uses `read_file`, `edit_file`, `run_shell`, and related names. |
-
-`AUVRYNT_TOOL_MODE` controls the tool surface.
-
-| Value | Behavior |
-| --- | --- |
-| `minimal` | Default. Disables dedicated search and list tools. Clients use the shell tool with `rg`, `grep`, `find`, `ls`, or `tree` for inspection. |
-| `full` | Enables dedicated `grep`, `glob`, and `ls` tools. |
-
-## Widgets
-
-`AUVRYNT_WIDGETS` controls ChatGPT Apps iframe usage.
-
-| Value | Behavior |
-| --- | --- |
-| `full` | Default. Widget UI is attached to exposed workspace, file, edit, and shell tools. |
-| `changes` | Enables the aggregate `show_changes` tool and attaches widget UI to `open_workspace` and `show_changes`. |
-| `off` | Disables widget UI. |
-
-## Skills
-
-| Variable | Purpose |
-| --- | --- |
-| `AUVRYNT_SKILLS` | Set to `0` to hide skills. Enabled by default. |
-| `AUVRYNT_AGENT_DIR` | Defaults to `~/.codex`. |
-| `AUVRYNT_SKILL_PATHS` | Optional comma-separated skill directories. |
-
-Example:
-
-```bash
-AUVRYNT_SKILL_PATHS="$HOME/.codex/skills,$HOME/.claude/skills" \
+```
+
+## Core Environment Variables
+
+| Variable | Purpose |
+| --- | --- |
+| `HOST` | Local bind host. Defaults to `127.0.0.1`. |
+| `PORT` | Local port. Defaults to `49321`. |
+| `AUVRYNT_ALLOWED_ROOTS` | Comma-separated local roots that workspaces may open. |
+| `AUVRYNT_PUBLIC_BASE_URL` | Public origin used by foreground `auvrynt serve`, without `/mcp`. Non-loopback origins must use HTTPS. Managed `auvrynt start` supplies its tunnel URL automatically. |
+| `AUVRYNT_TUNNEL_PROVIDER` | Managed background tunnel: `cloudflare` (default), `ngrok`, or `custom`. A custom provider can remain externally managed or use a Cloudflare Named Tunnel token so Auvrynt starts it. |
+| `AUVRYNT_CLOUDFLARE_TUNNEL_TOKEN` | Optional non-Windows Cloudflare Named Tunnel token. On Windows, custom mode controls the installed `cloudflared` service with `sc.exe`; the service must already contain the Named Tunnel token. |
+| `AUVRYNT_NGROK_AUTHTOKEN` | Optional ngrok token when ngrok is not already authenticated locally. |
+| `AUVRYNT_NGROK_URL` | Optional stable HTTPS origin reserved on the ngrok account, such as `https://your-name.ngrok.app`. Auvrynt passes it through ngrok's `--url` option. |
+| `AUVRYNT_ALLOWED_HOSTS` | Optional Host header allowlist override. |
+| `AUVRYNT_OAUTH_OWNER_TOKEN` | Owner token for OAuth approval. Must be at least 16 characters. |
+| `AUVRYNT_WORKTREE_ROOT` | Directory for managed Git worktrees. Defaults to `~/.auvrynt/worktrees`. |
+| `AUVRYNT_STATE_DIR` | Directory for SQLite state. Defaults to `~/.local/share/auvrynt`. |
+| `AUVRYNT_SESSION_IDLE_MS` | MCP session inactivity before automatic closure. Defaults to 12 hours; valid range is 1 minute to 7 days. Sessions with in-flight requests or tool calls are not expired. |
+| `AUVRYNT_DISCONNECT_GRACE_MS` | Optional retention time after a session becomes disconnected. Defaults to `0`, so an idle session closes at its timeout without an additional grace period. Persistent processes started with `start_process` continue independently. |
+| `AUVRYNT_MAX_SESSIONS` | Maximum reserved and established MCP sessions across all OAuth clients. Defaults to 999 and cannot be raised above 999. The Connectivity tab can persist any value from 1 to 999 when this environment variable is unset. |
+| `AUVRYNT_MAX_SESSIONS_PER_CLIENT` | Maximum reserved and established MCP sessions for one OAuth client. Defaults to the global limit and cannot be raised above 999. The Connectivity tab keeps both persisted limits aligned. |
+| `AUVRYNT_SERENA_ENABLED` | Enables the Serena runtime. When unset, startup enables Serena only if its executable or process is detected. Set to `0` to disable it completely. |
+| `AUVRYNT_SERENA_INTEGRATION_ENABLED` | Controls whether Serena tools are advertised to MCP clients. When unset, detection decides the default. Disabling it removes Serena from active clients' tool lists and stops active Serena sessions. |
+| `AUVRYNT_ASEPRITE_ENABLED` | Controls whether native Aseprite pixel-art tools are advertised. Defaults to enabled. |
+| `AUVRYNT_ASEPRITE_PATH` | Optional direct path to `aseprite.exe`/`aseprite`. |
+| `AUVRYNT_ASEPRITE_SOURCE_PATH` | Optional Aseprite source/build directory. Auvrynt checks `build/bin`, `bin`, then the source root for the executable. |
+
+## OAuth
+
+Auvrynt uses a single-user OAuth approval flow.
+
+| Variable | Default |
+| --- | --- |
+| `AUVRYNT_OAUTH_ACCESS_TOKEN_TTL_SECONDS` | `3600` |
+| `AUVRYNT_OAUTH_REFRESH_TOKEN_TTL_SECONDS` | `2592000` |
+| `AUVRYNT_OAUTH_SCOPES` | `auvrynt:read,auvrynt:write,auvrynt:process,auvrynt:web,auvrynt:software,auvrynt:godot,auvrynt:blender,auvrynt:aseprite,auvrynt:serena` |
+| `AUVRYNT_OAUTH_ALLOWED_REDIRECT_HOSTS` | `grok.com,console.x.ai,chatgpt.com,claude.ai,claude.com,anthropic.com,oauth.lovable.app,lovable.app,lovable.dev,api.lovable.dev,bolt.new,clusy.io,app.clusy.io,docs.clusy.io,localhost,127.0.0.1` |
+
+### Header-only MCP clients (Clusy and similar)
+
+Some hosts only support **Streamable HTTP + custom headers** and never open the browser `/authorize` page. For those clients, Auvrynt accepts the **Owner token** as a Bearer access token:
+
+```text
+Authorization: Bearer <AUVRYNT_OWNER_TOKEN>
+```
+
+That grant uses client id `auvrynt-owner-bearer` and the configured `AUVRYNT_OAUTH_SCOPES`. Prefer OAuth for Grok/Claude/ChatGPT; use Owner Bearer only for header-only hosts. Rotate the Owner token (`auvrynt token reset`) if it is ever exposed.
+
+`auvrynt:blender-python` is intentionally **not** granted by default. Add it to `AUVRYNT_OAUTH_SCOPES` only when a trusted client must use the arbitrary Blender Python escape hatch. Auvrynt enforces scopes per tool call, not only at login.
+
+OAuth scopes are the durable capability envelope; integration profiles are a second local execution gate. Changing profiles updates that local gate without closing MCP sessions or changing the public tunnel URL. Disabled integration tools are removed from active MCP tool lists, so agents do not keep planning calls to unavailable integrations. When the owner explicitly enables a profile, existing tokens receive only the required scopes that are already allowed by `AUVRYNT_OAUTH_SCOPES`.
+
+MCP clients discover metadata from:
+
+```text
+/.well-known/oauth-protected-resource/mcp
+/.well-known/oauth-authorization-server
+```
+
+## Tool Modes
+
+`AUVRYNT_TOOL_NAMING` controls tool names.
+
+| Value | Behavior |
+| --- | --- |
+| `short` | Default. Uses `read`, `edit`, `bash`, and related names. |
+| `legacy` | Uses `read_file`, `edit_file`, `run_shell`, and related names. |
+
+`AUVRYNT_TOOL_MODE` controls the tool surface.
+
+| Value | Behavior |
+| --- | --- |
+| `minimal` | Default. Disables dedicated search and list tools. Clients use the shell tool with `rg`, `grep`, `find`, `ls`, or `tree` for inspection. |
+| `full` | Enables dedicated `grep`, `glob`, and `ls` tools. |
+
+## Widgets
+
+`AUVRYNT_WIDGETS` controls ChatGPT Apps iframe usage.
+
+| Value | Behavior |
+| --- | --- |
+| `full` | Default. Widget UI is attached to exposed workspace, file, edit, and shell tools. |
+| `changes` | Enables the aggregate `show_changes` tool and attaches widget UI to `open_workspace` and `show_changes`. |
+| `off` | Disables widget UI. |
+
+## Skills
+
+| Variable | Purpose |
+| --- | --- |
+| `AUVRYNT_SKILLS` | Set to `0` to hide skills. Enabled by default. |
+| `AUVRYNT_AGENT_DIR` | Defaults to `~/.codex`. |
+| `AUVRYNT_SKILL_PATHS` | Optional comma-separated skill directories. |
+
+Example:
+
+```bash
+AUVRYNT_SKILL_PATHS="$HOME/.codex/skills,$HOME/.claude/skills" \
 npx auvrynt start
-```
-
-## Logging
-
-| Variable | Default |
-| --- | --- |
-| `AUVRYNT_LOG_LEVEL` | `info` |
-| `AUVRYNT_LOG_FORMAT` | `json` |
-| `AUVRYNT_LOG_REQUESTS` | `1` |
-| `AUVRYNT_LOG_ASSETS` | `0` |
-| `AUVRYNT_LOG_TOOL_CALLS` | `1` |
-| `AUVRYNT_LOG_SHELL_COMMANDS` | `0` |
-| `AUVRYNT_TRUST_PROXY` | `0` |
-
-Set `AUVRYNT_LOG_FORMAT=pretty` for local debugging.
-
-Set `AUVRYNT_LOG_SHELL_COMMANDS=1` only when you intentionally want command
-previews in logs.
-
-## Env-Only Example
-
-```bash
-AUVRYNT_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)" \
-AUVRYNT_ALLOWED_ROOTS="$HOME/personal,$HOME/work" \
-AUVRYNT_PUBLIC_BASE_URL="https://auvrynt.example.com" \
-AUVRYNT_WORKTREE_ROOT="$HOME/.auvrynt/worktrees" \
-AUVRYNT_TOOL_MODE="minimal" \
-AUVRYNT_TOOL_NAMING="short" \
-AUVRYNT_WIDGETS="full" \
+```
+
+## Logging
+
+| Variable | Default |
+| --- | --- |
+| `AUVRYNT_LOG_LEVEL` | `info` |
+| `AUVRYNT_LOG_FORMAT` | `json` |
+| `AUVRYNT_LOG_REQUESTS` | `1` |
+| `AUVRYNT_LOG_ASSETS` | `0` |
+| `AUVRYNT_LOG_TOOL_CALLS` | `1` |
+| `AUVRYNT_LOG_SHELL_COMMANDS` | `0` |
+
+Auvrynt trusts forwarded client information only from an immediate loopback proxy. This is fixed behavior rather than a runtime toggle so direct remote clients cannot opt into spoofable forwarding headers.
+
+Plain HTTP public origins are rejected unless the hostname is loopback (`localhost`, `127.0.0.0/8`, or `::1`). Use HTTPS for every tunnel, reverse proxy, LAN hostname, and public deployment.
+
+Run `auvrynt tunnel` to switch the managed provider interactively. With ngrok, leaving the stable URL blank uses an assigned URL; supplying `AUVRYNT_NGROK_URL` or saving the same value through the tunnel command keeps that origin across hard restarts as long as the reservation remains available. Auvrynt discovers the active ngrok URL from that process's structured startup logs rather than querying the shared `127.0.0.1:4040` inspector API, so another local ngrok process cannot be mistaken for Auvrynt's tunnel.
+
+Set `AUVRYNT_LOG_FORMAT=pretty` for local debugging.
+
+Set `AUVRYNT_LOG_SHELL_COMMANDS=1` only when you intentionally want command
+previews in logs.
+
+## Env-Only Example
+
+```bash
+AUVRYNT_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)" \
+AUVRYNT_ALLOWED_ROOTS="$HOME/personal,$HOME/work" \
+AUVRYNT_PUBLIC_BASE_URL="https://auvrynt.example.com" \
+AUVRYNT_WORKTREE_ROOT="$HOME/.auvrynt/worktrees" \
+AUVRYNT_TOOL_MODE="minimal" \
+AUVRYNT_TOOL_NAMING="short" \
+AUVRYNT_WIDGETS="full" \
 npx auvrynt start
-```
-
-The environment assignments must be part of the same command invocation, or
-exported first.
+```
+
+The environment assignments must be part of the same command invocation, or
+exported first.

package/docs/diagnostics.md

@@ -0,0 +1,79 @@
+# Diagnostics Endpoints
+
+Auvrynt exposes two unauthenticated diagnostic HTTP endpoints for health monitoring. Detailed process and resource information is returned only to loopback clients. Requests arriving through a trusted local tunnel proxy receive minimal responses so public health checks do not disclose internal state.
+
+Both endpoints send `Cache-Control: no-store`.
+
+## /healthz
+
+Simple liveness check with no database or external I/O.
+
+### Public response (200 OK)
+
+```json
+{
+  "ok": true
+}
+```
+
+### Loopback response (200 OK)
+
+```json
+{
+  "ok": true,
+  "name": "auvrynt",
+  "pid": 12345,
+  "uptimeSeconds": 3600
+}
+```
+
+## /readyz
+
+Readiness endpoint. It returns HTTP 503 while the server is shutting down or reconfiguring.
+
+### Public response
+
+```json
+{
+  "ready": true
+}
+```
+
+The same minimal shape is returned with HTTP 503 and `ready: false` when unavailable.
+
+### Loopback response (200 OK)
+
+```json
+{
+  "ready": true,
+  "sessions": 1,
+  "sessionsByState": {
+    "initializing": 0,
+    "active": 1,
+    "disconnected": 0,
+    "closing": 0
+  },
+  "activeMcpRequests": 0,
+  "activeToolCalls": 0,
+  "runningProcesses": 0,
+  "eventLoopDelay": 1,
+  "memory": {
+    "rss": 123456789,
+    "heapTotal": 98765432,
+    "heapUsed": 45678901
+  },
+  "integrationQueues": {}
+}
+```
+
+The detailed loopback response may include additional bounded diagnostic fields as the server evolves.
+
+### Usage
+
+- Use `/healthz` for load-balancer and tunnel liveness checks.
+- Use `/readyz` to decide whether new MCP work should be accepted.
+- Inspect `/readyz` locally when diagnosing sessions, process load, memory, integration queues, or a 502 response.
+- Long-running MCP SSE responses emit a comment heartbeat every 15 seconds so tunnels do not treat a silent build or render as abandoned.
+- Oversized tool results are truncated or have inline binary omitted before transmission. Request a narrower file range, fewer results, or a smaller image when the response includes an Auvrynt truncation notice.
+- Browser screenshots and Blender/image outputs are still saved locally when they are too large to embed safely.
+- Do not expose another proxy layer that rewrites remote requests to appear as direct loopback traffic.