@treeport/pi 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noice Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# `@treeport/pi`
+
+Give Pi compact Treeport context and access to the Treeport CLI.
+
+## Requirements
+
+Install these applications first:
+
+- Treeport `0.5.0` or later;
+- Pi `0.84.3` or later;
+- Node.js 24 or later;
+- macOS or Linux.
+
+Make sure that the `treeport` command is on `PATH`.
+
+## Install
+
+Install the package globally in Pi:
+
+```sh
+pi install npm:@treeport/pi
+```
+
+The package contains a Pi extension and the detailed Treeport skill.
+
+The extension starts only in a terminal that Treeport manages.
+
+A managed Pi session shows this footer status:
+
+```text
+treeport · <tree-name>
+```
+
+Outside Treeport, the extension adds no guidance, notification, or footer status.
+
+## Use natural requests
+
+Ask Pi to do the work. You do not have to name Treeport.
+
+Examples:
+
+- “Start the development server.”
+- “Stop the development server.”
+- “Open the app and check the settings page.”
+- “Do this side quest in a separate tree.”
+
+In a managed session, the extension briefly defines Treeport projects and trees.
+
+It includes the current project and tree names. It does not include IDs, paths, or the daemon URL.
+
+The guidance tells Pi to use the `treeport` CLI through its standard Bash tool.
+
+Pi uses a persistent terminal for a long-running process. Pi uses Bash directly for a finite command.
+
+When you ask Pi to stop a process, Pi can delete its persistent terminal. Pi must not delete its own terminal.
+
+For a side quest, Pi can use another terminal in the current tree. It can use `treeport spawn` for another tree.
+
+Pi can control visible browser tabs when the Treeport CLI and daemon support browser commands.
+
+The browser tabs stay open so you can inspect them.
+
+The guidance requires your approval before a Chromium installation.
+
+## Use the skill for detailed workflows
+
+The bundled skill contains detailed Treeport CLI procedures.
+
+Pi does not need the skill for routine terminal or browser operations.
+
+Use the skill for lifecycle operations, remote access, updates, recovery, or complex child-tree work.
+
+## Remove
+
+Remove the package from Pi:
+
+```sh
+pi remove npm:@treeport/pi
+```

package/extensions/treeport/index.ts

@@ -0,0 +1,231 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Type, type Static } from 'typebox'
+import { runTreeportJson } from './treeport-cli.ts'
+
+const CONTEXT_TIMEOUT_MS = 5_000
+
+interface ManagedContext {
+  project: {
+    id: string
+    name: string
+  }
+  worktree: {
+    id: string
+    projectId: string
+    name: string
+  }
+  terminal: {
+    id: string
+    worktreeId: string
+  }
+}
+
+const BrowserStatusSchema = Type.Object(
+  {
+    installed: Type.Boolean(),
+    launchReady: Type.Boolean()
+  },
+  { additionalProperties: true }
+)
+const ContextSchema = Type.Union([
+  Type.Object(
+    {
+      managed: Type.Literal(false),
+      reason: Type.String()
+    },
+    { additionalProperties: true }
+  ),
+  Type.Object(
+    {
+      managed: Type.Literal(true),
+      apiUrl: Type.String({ minLength: 1 }),
+      daemonLifecycle: Type.Union([
+        Type.Literal('treeport'),
+        Type.Literal('service'),
+        Type.Literal('external')
+      ]),
+      project: Type.Object(
+        {
+          id: Type.String({ minLength: 1 }),
+          name: Type.String({ minLength: 1 }),
+          kind: Type.Union([Type.Literal('repository'), Type.Literal('folder')])
+        },
+        { additionalProperties: true }
+      ),
+      worktree: Type.Object(
+        {
+          id: Type.String({ minLength: 1 }),
+          projectId: Type.String({ minLength: 1 }),
+          name: Type.String({ minLength: 1 }),
+          path: Type.String({ minLength: 1 })
+        },
+        { additionalProperties: true }
+      ),
+      terminal: Type.Object(
+        {
+          id: Type.String({ minLength: 1 }),
+          worktreeId: Type.String({ minLength: 1 }),
+          name: Type.String({ minLength: 1 })
+        },
+        { additionalProperties: true }
+      )
+    },
+    { additionalProperties: true }
+  )
+])
+
+type ContextOutput = Static<typeof ContextSchema>
+
+function managedContext(value: ContextOutput): ManagedContext | null {
+  if (value.managed === false) {
+    return null
+  }
+
+  if (
+    value.worktree.projectId !== value.project.id ||
+    value.terminal.worktreeId !== value.worktree.id
+  ) {
+    return null
+  }
+
+  let parsedApiUrl: URL
+  try {
+    parsedApiUrl = new URL(value.apiUrl)
+  } catch {
+    return null
+  }
+  if (!['http:', 'https:'].includes(parsedApiUrl.protocol)) {
+    return null
+  }
+
+  return {
+    project: value.project,
+    worktree: value.worktree,
+    terminal: value.terminal
+  }
+}
+
+export default function treeportExtension(pi: ExtensionAPI): void {
+  let guidance: string | null = null
+  let badgeVisible = false
+
+  pi.on('session_start', async (_event, sessionContext) => {
+    guidance = null
+    let detectedValue: ContextOutput
+    try {
+      detectedValue = await runTreeportJson(pi, ['context'], ContextSchema, {
+        cwd: sessionContext.cwd,
+        signal: undefined,
+        timeout: CONTEXT_TIMEOUT_MS
+      })
+    } catch {
+      const injectedIds = [
+        process.env.TREEPORT_PROJECT_ID,
+        process.env.TREEPORT_WORKTREE_ID,
+        process.env.TREEPORT_TERMINAL_ID
+      ].some((value) => Boolean(value?.trim()))
+      if (injectedIds && sessionContext.hasUI) {
+        sessionContext.ui.notify(
+          'Treeport context is unavailable. The Treeport integration is inactive.',
+          'warning'
+        )
+      }
+
+      return
+    }
+
+    if (detectedValue.managed === false) {
+      return
+    }
+
+    const detected = managedContext(detectedValue)
+    if (!detected) {
+      const injectedIds = [
+        process.env.TREEPORT_PROJECT_ID,
+        process.env.TREEPORT_WORKTREE_ID,
+        process.env.TREEPORT_TERMINAL_ID
+      ].some((value) => Boolean(value?.trim()))
+      if (injectedIds && sessionContext.hasUI) {
+        sessionContext.ui.notify(
+          'Treeport context is invalid. The Treeport integration is inactive.',
+          'warning'
+        )
+      }
+
+      return
+    }
+
+    let browserCommandsAvailable = true
+    try {
+      await runTreeportJson(pi, ['browser', 'status'], BrowserStatusSchema, {
+        cwd: sessionContext.cwd,
+        signal: undefined,
+        timeout: CONTEXT_TIMEOUT_MS
+      })
+    } catch {
+      browserCommandsAvailable = false
+    }
+
+    const guidanceLines = [
+      'Treeport context:',
+      browserCommandsAvailable
+        ? 'Treeport is a worktree-first workspace for projects, trees, persistent terminals, and browser tabs.'
+        : 'Treeport is a worktree-first workspace for projects, trees, and persistent terminals.',
+      'A project is a registered repository or folder. A tree is its main checkout or a linked Git worktree.',
+      `This session runs in project ${JSON.stringify(
+        detected.project.name
+      )} and tree ${JSON.stringify(detected.worktree.name)}.`,
+      'Use the `treeport` CLI through bash for Treeport operations. Use `--json` when you must parse a result.',
+      'Use bash directly for finite commands that Pi must await.',
+      'For a persistent process, run `treeport terminal create --worktree . --name <name> -- <program> <arg> ...`.',
+      'Pass the child program and its arguments after `--`. Do not use an implicit shell command string.',
+      'Observe persistent terminals with `treeport terminal inspect`, `treeport terminal capture`, or `treeport terminal wait`.',
+      'Do not poll through repeated model calls. Sleep and capture in one bash call, such as `sleep 5; treeport terminal capture <id>`.',
+      '`treeport terminal wait --until idle` observes OSC progress. It is not a readiness check and can return immediately.',
+      'Delete a terminal only when the user asks to stop or close its process. Never delete this Pi session terminal.',
+      'A side quest is independent work in another persistent terminal. Use `treeport terminal create` here or `treeport spawn` for another tree.',
+      ...(browserCommandsAvailable
+        ? [
+            'Use `treeport browser` commands for visible browser tabs. Take a new snapshot after navigation or a runtime change.',
+            'Leave browser tabs open for user inspection. Do not install Chromium without user approval.',
+            'Do not put secrets in browser URLs or command arguments.'
+          ]
+        : []),
+      'Use `treeport <area> <command> --help` for exact syntax. Do not load the Treeport skill for these routine operations.'
+    ]
+    guidance = guidanceLines.join('\n')
+
+    if (!browserCommandsAvailable && sessionContext.hasUI) {
+      sessionContext.ui.notify(
+        'Treeport browser commands are unavailable in this session.',
+        'warning'
+      )
+    }
+
+    if (sessionContext.hasUI) {
+      sessionContext.ui.setStatus(
+        'treeport',
+        sessionContext.ui.theme.fg(
+          'accent',
+          `treeport · ${detected.worktree.name}`
+        )
+      )
+      badgeVisible = true
+    }
+  })
+
+  pi.on('before_agent_start', (event) => {
+    if (!guidance) {
+      return
+    }
+
+    return { systemPrompt: `${event.systemPrompt}\n\n${guidance}` }
+  })
+
+  pi.on('session_shutdown', (_event, sessionContext) => {
+    if (badgeVisible) {
+      sessionContext.ui.setStatus('treeport', undefined)
+      badgeVisible = false
+    }
+  })
+}

package/extensions/treeport/treeport-cli.ts

@@ -0,0 +1,146 @@
+import { constants as fsConstants } from 'node:fs'
+import { access } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import type { ExecOptions, ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Type, type Static, type TSchema } from 'typebox'
+import { Value } from 'typebox/value'
+
+const TreeportCliErrorBodySchema = Type.Object(
+  {
+    error: Type.Object(
+      {
+        code: Type.String(),
+        message: Type.String()
+      },
+      { additionalProperties: true }
+    )
+  },
+  { additionalProperties: true }
+)
+
+type TreeportCliErrorBody = Static<typeof TreeportCliErrorBodySchema>
+
+class TreeportCliError extends Error {
+  constructor(
+    readonly code: string,
+    message: string
+  ) {
+    super(`[${code}] ${message}`)
+    this.name = 'TreeportCliError'
+  }
+}
+
+function parseJson<T extends TSchema>(
+  value: string,
+  schema: T
+): Static<T> | null {
+  try {
+    return Value.Parse(schema, JSON.parse(value))
+  } catch {
+    return null
+  }
+}
+
+function conciseError(value: string): string {
+  return (value.split(/\n\n(?:AI agents:|Usage:)/, 1)[0] ?? value).trim()
+}
+
+async function treeportExecutable(): Promise<string> {
+  const configured = process.env.TREEPORT_CLI_ENTRYPOINT?.trim()
+  if (
+    configured &&
+    (await access(configured, fsConstants.X_OK).then(
+      () => true,
+      () => false
+    ))
+  ) {
+    return configured
+  }
+
+  const daemonRecord = process.env.TREEPORT_DAEMON_RECORD?.trim()
+  if (daemonRecord) {
+    const developmentRuntime = dirname(dirname(daemonRecord))
+    if (basename(developmentRuntime) === '.treeport-dev') {
+      const developmentCli = join(
+        dirname(developmentRuntime),
+        '.treeport-dev-dist/node/cli/index.js'
+      )
+      if (
+        await access(developmentCli, fsConstants.X_OK).then(
+          () => true,
+          () => false
+        )
+      ) {
+        return developmentCli
+      }
+    }
+  }
+
+  return 'treeport'
+}
+
+export async function runTreeportJson<T extends TSchema>(
+  pi: Pick<ExtensionAPI, 'exec'>,
+  args: readonly string[],
+  schema: T,
+  options: {
+    cwd: string
+    signal: AbortSignal | undefined
+    timeout: number
+  }
+): Promise<Static<T>> {
+  const jsonArgs = [...args]
+  const separator = jsonArgs.indexOf('--')
+  jsonArgs.splice(separator === -1 ? jsonArgs.length : separator, 0, '--json')
+
+  const execOptions: ExecOptions = {
+    cwd: options.cwd,
+    timeout: options.timeout
+  }
+  if (options.signal) {
+    execOptions.signal = options.signal
+  }
+
+  const result = await pi.exec(
+    await treeportExecutable(),
+    jsonArgs,
+    execOptions
+  )
+
+  if (result.code !== 0) {
+    const parsed: TreeportCliErrorBody | null = parseJson(
+      result.stderr.trim(),
+      TreeportCliErrorBodySchema
+    )
+    const code = parsed
+      ? parsed.error.code
+      : result.killed
+        ? options.signal?.aborted
+          ? 'TREEPORT_CANCELLED'
+          : 'TREEPORT_EXECUTION_TIMEOUT'
+        : 'TREEPORT_EXECUTION_FAILED'
+    const message = parsed
+      ? conciseError(parsed.error.message)
+      : result.killed
+        ? options.signal?.aborted
+          ? 'The Treeport command was cancelled.'
+          : 'The Treeport command reached its execution time limit.'
+        : result.stderr.trim()
+          ? `${conciseError(result.stderr)} (Treeport exit code ${result.code}).`
+          : `Treeport exited with code ${result.code}.`
+    throw new TreeportCliError(code, message)
+  }
+
+  const output = result.stdout.trim()
+  const parsed: Static<T> | null = parseJson(output, schema)
+  if (parsed === null) {
+    throw new TreeportCliError(
+      'TREEPORT_INVALID_JSON',
+      output
+        ? 'Treeport returned invalid JSON.'
+        : 'Treeport returned no JSON output.'
+    )
+  }
+
+  return parsed
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@treeport/pi",
+  "version": "0.6.1",
+  "description": "Treeport context and CLI guidance for Pi.",
+  "type": "module",
+  "files": [
+    "extensions/treeport/index.ts",
+    "extensions/treeport/treeport-cli.ts",
+    "skills/treeport/SKILL.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "pi-package",
+    "treeport",
+    "coding-agent"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/treeport/index.ts"
+    ],
+    "skills": [
+      "./skills/treeport"
+    ]
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noice-tech/treeport.git",
+    "directory": "packages/pi"
+  },
+  "bugs": {
+    "url": "https://github.com/noice-tech/treeport/issues"
+  },
+  "homepage": "https://treeport.app",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.3",
+    "typebox": "^1.3.7"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json --pretty",
+    "test:package": "node scripts/check-package.mjs"
+  }
+}

package/skills/treeport/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: treeport
+description: Detailed Treeport CLI guidance for child-tree orchestration, lifecycle, services, remote access, updates, and recovery. Use when compact Pi guidance or command help is not sufficient. Do not load for routine background processes or browser tabs in a managed Pi session.
+compatibility: Requires the treeport CLI on PATH and a reachable Treeport daemon. Creation commands also require the requested child executable to be installed.
+---
+
+# Treeport
+
+In a managed Pi session, use the injected CLI guidance for routine terminal and browser operations. Load this skill only when you need more detail.
+
+Treeport is a generic terminal and tree layer. Its terminals are persistent tmux sessions that appear in the Treeport UI. A user can open a created terminal, take control of the normal application TUI, and continue working in the same session.
+
+Treeport does not define task sources, planning or approval states, agent tool policies, or provider-specific workflows. The caller owns names, commands, prompts, and higher-level orchestration.
+
+## Operating rules
+
+- Use normal CLI output when you are reading the result. Use `--json` only for programmatic extraction or branching.
+- Treat command arguments after `--` as an argv array. Do not turn them into a shell command string.
+- Do not use `eval` or an implicit `sh -lc`. Launch a shell explicitly only when the caller intentionally requests shell semantics.
+- Do not place untrusted titles, prompts, or other external text into interpolated shell fragments. Pass each value as one argument or use a caller-managed file when the child supports file arguments.
+- Never delete a terminal or remove a tree unless the user explicitly asks.
+- Obey the daemon lifecycle reported by `treeport context`.
+- When the lifecycle is `external`, never run `treeport start`, `treeport stop`, or `treeport remote enable`.
+- In the external lifecycle, the parent process owns startup, shutdown, and remote exposure.
+- When the lifecycle is `service`, normal `start` and `stop` delegate to the OS manager.
+- Use bare `treeport update` to update a supported local npm installation. It preserves tmux terminals and an enabled service, and restarts only a daemon that was running.
+- Never run bare `treeport update` for an external or selected remote daemon.
+- Never invoke `sudo` for a normal service or update operation.
+- Normal macOS service mode is a user/login LaunchAgent and does not need an administrator.
+- Advanced headless mode is explicit.
+- If an existing headless service prints an administrator command, report the command and wait for the user.
+- Do not restrict a launched agent's normal tools or make it ephemeral unless the caller explicitly asks. The persistent interactive session is intended to remain useful when the user takes over.
+
+## Understand the current context
+
+Run:
+
+```sh
+treeport context
+```
+
+Inside a managed terminal, this reports the current project, tree, terminal, paths, statuses, IDs, tree context values, and daemon URL. User-supplied context can contain an issue identifier, a task description, or other information for the tree. Use these values as task input when the caller asks you to work from the tree context. It reports whether Treeport, the OS service, or an external process manages the daemon lifecycle. It resolves the injected IDs strictly. It does not guess identity from the current path.
+
+Outside Treeport it reports that the terminal is not managed and exits successfully. `TREEPORT_API_URL` may be configured outside a managed terminal; if any context ID is present, however, all injected values are required. Partial IDs or IDs that no longer belong together fail instead of falling back to path inference.
+
+Use the exact IDs from this command when an operation targets a different project or tree. `.` is a convenient shorthand for the current project or tree.
+
+When the current folder is in the target project, omit `--project` from `worktree create` and `spawn`. Treeport detects the registered project from the current folder.
+
+## Create a terminal in the current tree
+
+Create a persistent login shell:
+
+```sh
+treeport terminal create --worktree <tree-id> --name <terminal-name>
+```
+
+Launch a program directly:
+
+```sh
+treeport terminal create --worktree <tree-id> --name <terminal-name> -- <program> <arg> ...
+```
+
+The command returns after Treeport creates the tmux session. The program continues independently of the browser and of the caller that created it.
+
+## Create a child tree and terminal
+
+Create a linked tree and its first persistent terminal together:
+
+```sh
+treeport spawn \
+  --worktree-name <tree-name> \
+  --name <terminal-name> \
+  -- <program> <arg> ...
+```
+
+The child program and its arguments are entirely caller-owned. Treeport preserves them but does not add prompts, modes, capability restrictions, or lifecycle policy.
+
+By default, Treeport bases the tree on the fetched remote default branch. Add `--from-current` only for the current tree's committed `HEAD`. Uncommitted changes are not copied.
+
+Treeport serializes tree mutations per project. If a caller needs several child trees, create them one at a time. Their terminal programs can run concurrently after creation.
+
+## Interpret creation results
+
+A successful `terminal create` means the tmux session was created. The requested program can still exit later.
+
+`spawn` is intentionally non-atomic after Git creates the worktree:
+
+- A terminal ID means the persistent session was created.
+- `terminalError` means the tree remains but its initial terminal could not be created.
+- `setupError` means tree setup could not be prepared. A retained terminal may display that error and exit without launching the requested program.
+- Setup tasks can also fail after the create response. Their output and failure remain visible in the retained terminal.
+
+Report partial creation with the returned tree and terminal IDs. Do not blindly rerun `spawn`: the tree may already exist. Do not remove retained resources automatically.
+
+Inspect terminal inventory later with:
+
+```sh
+treeport terminal list --worktree <tree-id>
+```
+
+Inspect one terminal's refreshed process status and volatile runtime metadata with:
+
+```sh
+treeport terminal inspect <terminal-id>
+treeport terminal inspect <terminal-id> --json
+```
+
+Runtime metadata includes the title, current OSC `9;4` progress, last progress start and clear timestamps, and latest daemon-observed real BEL. BEL metadata also reports daemon-lifetime unread attention shared by every browser; inspection and waits never acknowledge it, while viewing the terminal acknowledges the exact observed BEL sequence. `.` resolves to the exact `TREEPORT_TERMINAL_ID` inside a managed terminal; it is not a name or path lookup.
+
+Read recent terminal contents with:
+
+```sh
+treeport terminal capture <terminal-id>
+treeport terminal capture <terminal-id> --lines 500
+treeport terminal capture <terminal-id> --json
+```
+
+Capture returns up to 200 pane rows by default. Plain output is the terminal text; JSON output includes the terminal ID, capture time, line limit, and content. `.` can be used for the current managed terminal.
+
+Wait for raw terminal conditions without polling or scraping output:
+
+```sh
+treeport terminal wait <terminal-id> --until working
+treeport terminal wait <terminal-id> --until idle --timeout 30m
+treeport terminal wait <terminal-id> --until bell
+treeport terminal wait <terminal-id> --until exit
+```
+
+- `idle` means no daemon-owned OSC progress is currently observed and can return immediately.
+- `working` means daemon-owned OSC progress is currently present and can return immediately. Every valid active progress frame renews a five-minute inactivity lease; an explicit clear or terminal/observer shutdown clears immediately.
+- `bell` means the next real BEL after the event subscription is established.
+- `exit` means the retained terminal process has exited.
+- Waits have no default timeout. Use a positive `ms`, `s`, `m`, or `h` duration when a deadline is required; Ctrl+C cancels.
+
+Treeport does not infer agent settlement. An orchestrator can inspect first, wait for `working` if no progress cycle has been observed, and then wait for `idle`. Progress depends on the child application emitting OSC `9;4`; for Pi, `terminal.showTerminalProgress` must be enabled. Applications should clear progress or refresh active progress more frequently than the five-minute lease. A null progress value is not proof that every application supports progress reporting.
+
+## Inspect the worktree application in a browser tab
+
+The Browser primitive has one live runtime for each browser tab.
+
+Electron owns the visible `<webview>` page for a local desktop connection.
+
+Playwright controls managed Chromium for a web or remote desktop connection.
+
+Never attach Treeport to a personal browser profile.
+
+First, inspect the available browser tabs:
+
+```sh
+treeport browser list
+```
+
+If no browser tab is open, open one in the current tree:
+
+```sh
+treeport browser open --worktree .
+```
+
+Use these commands on the current live page:
+
+```sh
+treeport browser snapshot
+treeport browser click e12
+treeport browser fill e14 "value"
+treeport browser press Enter
+treeport browser console
+treeport browser network
+treeport browser screenshot
+```
+
+The commands select the only browser tab in the current tree.
+
+When more than one browser tab exists, add `--panel <panel-id>`.
+
+Snapshot references belong to one runtime generation.
+
+Take a new snapshot after navigation or a runtime change.
+
+A local desktop owner does not need managed Chromium.
+
+If no local owner exists, check managed Chromium before daemon automation:
+
+```sh
+treeport browser status
+```
+
+Ask the user before you run `treeport browser install`.
+
+Leave the browser tab open so the user can inspect the result.
+
+## Automation and integrations
+
+Extensions and scripts should add `--json` before the `--` command separator:
+
+```sh
+treeport context --json
+
+treeport terminal create \
+  --worktree <tree-id> \
+  --name <terminal-name> \
+  --json -- <program> <arg> ...
+
+treeport spawn \
+  --worktree-name <tree-name> \
+  --name <terminal-name> \
+  --json -- <program> <arg> ...
+```
+
+JSON success output is written to stdout. JSON errors use `{ "error": { "code", "message", "details"? } }` on stderr. Relevant exit codes are:
+
+- `0`: command completed; for `spawn`, still inspect `terminal`, `terminalError`, and `setupError`.
+- `2`: invalid CLI usage.
+- `3`: the daemon could not be reached or its event stream failed.
+- `4`: a terminal wait timed out.
+- `5`: API, domain, or invalid-context refusal.
+- `130`: a terminal wait was interrupted with Ctrl+C.
+
+Treeport trusts the local OS boundary for loopback access and delegates supported remote authentication to Tailscale Serve. Do not expose the daemon through a direct network listener, invent credentials, or put secrets in command arguments or URLs.