berth v0.1.11

Which berth is this? Every surface people read now says, and a dashboard left running across an upgrade asks to be restarted.

Added

• berth names its version where people read its output: the dashboard header (ui :10000 · v0.1.11), the first line of berth check (berth 0.1.11 · 33 ports · …), and the session-start block (## Ports (berth 0.1.11)). A dashboard or session left running across an upgrade now shows the version it is actually running. Machine-read output (env, --json, which already carried version) is unchanged.
• The dashboard notices when a newer berth is installed than the one serving it, whether npm replaced it in place or a newer Claude Code plugin version sits beside it in the plugin cache, and the header says 0.1.12 installed, restart berth ui. /api/state carries it as runtime.installed; the check reads berth's own package.json files, at most once a minute.

berth v0.1.10

Past the TTL. A scratch port that outlived the process that claimed it no longer reads as ok.

Added

• A ninth port state, overstay: a dynamic lease past its TTL whose claiming process is gone while its server is still bound. It was reported as ok, so berth check showed nothing to attend to while a scratch port was being used as a permanent one. It counts toward "need attention", suggests a permanent home (berth project add <dir>, or berth claim --extra inside a registered project), is listed but never released by tidy (a new overstay array in tidy --json), and shows on the map as a hatched ok cell. The JSON change is additive (a new state value and summary.byState.overstay); a consumer that matches state exhaustively needs the new value. A lease whose claiming pid is alive stays ok whatever the TTL says (ADR-003 §6); a session resumed under a new pid does not count. See ADR-010.

Changed

• Documentation: the landing page's infographic alt text describes the second panel it gained in 0.1.9, instead of stopping at the one-digit example (#42).

berth v0.1.9

Two-digit projects. What the twenty-second project taught: the scheme was right, the way it was explained was not, and the one bound that failed silently now speaks.

Changed

• Documentation: the port rule is now taught as a subtraction rather than a digit position. Every explanation used a single-digit example, 13204 is project 3, worktree 2, smtp, and the infographic drew one box per digit — which reads as the rule and stops being true at P=10, where the thousands carry into the leading digit and 31010 is project 21, not project 1. README, the landing page, Concepts, the Claude Code rules block and examples/CLAUDE.ports.md now work the two-digit case, and the infographic gained a panel showing 31010 − 10000 = 21 · 0 · 10 (#42).

Fixed

• berth project add no longer drops Compose services in silence when a repository has more than ninety non-canonical ones. Extras slots run 10–99; past that, inferExtras quietly stopped assigning and the project was reported as registered with no hint that part of it had been left out. It now returns what it could not place, and project add warns with the count, the first few service names and the two ways out. berth claim --extra already failed loudly on the same exhaustion; the two paths now agree (#43).

Changed

• Documentation: the Claude Code guide now carries the Ports rules text for ~/.claude/CLAUDE.md under its own heading, which is where berth doctor sends a reader who has none. It previously forwarded them to examples/CLAUDE.ports.md, a file nobody reading the site has. The README's two references became absolute URLs so they resolve from an unpacked package as well. DESIGN.md and the ADRs keep their references: they are the historical record, and ADR-006's is the statement of the problem it solved (#40).

berth v0.1.8

First-run fix. What a user sees who installed from npm and never cloned the repository.

Fixed

• First run after npm install -g no longer points at a file the package does not contain. berth check, berth doctor and the SessionStart context text named examples/policy.example.toml, which ships only in the git repository, and none of them named berth init — the command that writes the policy and needs no files at all. All three now say berth init, and doctor's Claude rules row links the documentation site rather than examples/CLAUDE.ports.md. A test asserts no file under src/ cites a repository path again (#37).

berth v0.1.7

Readability fix. One rule for the map, stated in the code: a cell prints the part of its port that its position does not already imply.

Fixed

• Dashboard map: an extra's cell now prints its two-digit slot. A cell prints the part of its port that its position does not already imply — a role cell nothing (the row's base plus the worktree plus the cell's own index), an extra its slot (the map sorts extras by slot, so position gives their ordering and nothing more), a legacy cell the whole port. Eighteen anonymous cells on a project with eighteen extras were unreadable without hovering each one; they are now a role cell's width with the slot in them, dimmed where nothing holds the port (#34).

berth v0.1.6

Onboarding release. What the first real registration taught: a project's own services need no adoption when the evidence already attributes them, a shell hook that follows cd, a warning before a Compose override that cannot apply, berth tidy for the leftovers, and ADR-009 (proposed) for moving repositories off hardcoded ports.

Added

• ADR-009 (proposed, council-reviewed): how a registered repository stops hardcoding ports. Environment first, the project's own W0 port as the default, strict bind; a berth-migrate skill with one recipe per tool (#17); three scanner zones so a migrated default is never re-declared, and berth project declared --prune as a rail-guarded, audited exception to additive-only policy edits (#16).
• berth shell-init zsh|bash|fish prints a directory-change hook for your rc file: entering a registered project's checkout exports its ports, leaving it unsets them, and moving between two directories of the same project costs nothing (no berth process spawned unless the project root changed) (#21).
• berth env --shell --unset prints unset lines for every variable --shell would export in the same context, including the shared ones, and nothing else — what shell-init evals when leaving a project (#21).
• berth env --compose-override detects a mapped service whose currently-declared port is already held by a container without compose labels (started with docker run) and prints a per-service warning — the recreate command with its volumes, and a caution for an anonymous volume or an image that keeps state only in memory unless configured — instead of a silently ineffective override; berth who adds started by: compose <project> | docker run and mounted volume names to a container holder's evidence; berth doctor reports the Compose flavour on this machine (docker compose plugin, standalone docker-compose, or none) and its version, which the override output now names for the next step (#22).
• berth tidy [--project X] [--dry-run] [--json]: one human command that applies the leftover-cleanup plan an agent has already shown. --dry-run (and --json) list stale/orphan leases it would release, any owner, and unmanaged ports it can only suggest adopting; applying — human-only under ADR-008 — releases exactly that plan with one audit line per port and is idempotent. The human-only refusal message now explains why and, when it applies, names the berth tidy --project <name> apply path, and berth check's attention summary ends with one run: berth tidy --project <name> line per project with something to release (#20).

Changed

• The npm package's homepage is the documentation site (https://amiable-dev.github.io/berth/) instead of the README; npmjs.com and npm docs link there from the next release.
• Reconciler: a live holder inside a project's own block that is already attributed by evidence (compose working_dir label or process cwd) is now ok with no lease required, instead of unmanaged. PortRecord gains attribution: 'lease' | 'evidence'; a holder with no attribution stays unmanaged, and a container started outside Compose gets advisory copy that says so instead of the generic adopt text (#19).
• berth launch-json --write no longer writes a machine-specific cwd for the common case: entries omit cwd when it equals the repository root, and write it relative to the repository root when --cwd points elsewhere. After writing, .claude/launch.json is appended to .git/info/exclude (never .gitignore) unless it is already tracked or ignored, so it is never committed by accident; --no-exclude opts out (#23).
• berth env --shell outside a registered project no longer fails: it exits 0, prints only the machine-wide BERTH_SHARED_* exports plus a comment naming the fix (berth project add .), and writes nothing to stderr, so a shell rc file can eval it on every prompt without noise. --strict restores the old exit-1 behaviour; --dotenv, --compose-override and --json are unchanged and still fail loudly (#21).

berth v0.1.5

Docs release. A documentation site for engineers at https://amiable-dev.github.io/berth/, and the dashboard header links to it and to the repository.

Added

• Documentation site at https://amiable-dev.github.io/berth/ (VitePress in docs/, built and deployed by .github/workflows/docs.yml): getting started, concepts, day-to-day use, Claude Code and agents, the dashboard, troubleshooting, and CLI, policy, JSON/MCP and safety references, plus the design document and ADRs.
• The dashboard header links to the documentation and the GitHub repository (icons left of the search box).

Fixed

• Docs site: the theme's own templates (site title, search label, hero buttons, breadcrumb) rendered literally because the Vue delimiters had been changed to protect the Docker {{.Label}} examples in the research page. Those tables are now v-pre containers instead, and the docs build fails if unrendered templates reach the static HTML.

berth v0.1.4

Process release. Changelog entries are now enforced per pull request, governance documents the single-maintainer period, and the 0.1.1 release date is corrected.

Changed

• Every pull request must add a note under [Unreleased]: a required CI check fails otherwise (Dependabot PRs and the skip-changelog label are exempt). GOVERNANCE.md describes the single-maintainer period and what changes when a second maintainer joins.

berth v0.1.3

Agent sessions need nothing but the plugin. The plugin now carries bin/berth and puts it on each session's PATH, so berth works from Claude Code without a global install.

Added

• The plugin ships bin/berth, and the SessionStart hook puts it on the session's PATH, so berth works in every Bash call of a Claude Code session without a global npm install (BERTH_BIN is exported either way). The README now documents installation from an agent session and from a terminal separately, with a who-does-what table; the skills mention the MCP tools as an alternative to the CLI.

berth v0.1.2

The plugin release. berth becomes a Claude Code plugin (hooks, MCP server, two skills) installable from the repository's own marketplace; the CLI configures itself (berth init, berth project add); human-only commands are fenced off from agent sessions; the repository is hardened and every code-scanning finding is resolved.

Added

• berth init writes a generic starting policy; berth project add [path] registers a repository with the next free permanent number, its scanned declared ports and Compose-derived extras, additively and idempotently; berth project list (ADR-006).
• Claude Code plugin in the repository and the npm package: SessionStart/SessionEnd hooks, the MCP server and two skills, berth-ports (day-to-day) and berth-onboard (register the repo you are in), installable from the repo's own marketplace (ADR-007).
• README quick start: install, init, project add ., check; the example policy is now a worked example rather than the onboarding path.

Security

• Repository hardening: main ruleset (pull request required, six required checks, linear history, squash only, no force-push or deletion, no bypass), private vulnerability reporting, read-only default Actions token, Dependabot security updates and secret-scanning push protection; CodeQL findings resolved (TOCTOU reads, view dispatch, exception text in the dashboard API) and workflow installs pinned.
• Agent guardrail (ADR-008): free, any --force, hooks install|uninstall, worktrees prune, init --force and adopt --owner human run only for a human at an interactive terminal with no Claude marker in the environment, or with BERTH_ALLOW_DESTRUCTIVE=1 set deliberately; refusals and overrides are logged to ~/.local/state/berth/audit.log; shipped skills never name those commands and the MCP server exposes only self-scoped tools.
• Writers of policy.toml (project add, scan --write) serialise on a lock; project add requires a git repository root unless --allow-non-git.
• The plugin's hooks and MCP server start through hooks/run.sh, which finds Node in common version-manager locations and never fails a session when it cannot.