From c990236ed9cfa03b95d4cf4890d3100e049e1e27 Mon Sep 17 00:00:00 2001
From: Arthur <hello@arthware.dev>
Date: Sun, 20 Sep 2026 14:42:53 +0200
Subject: [PATCH 01/11] docs: document the commit message convention

Add a commit message section to docs/agent/dev.md, based on
Conventional Commits and the Git and Linux kernel guidelines:

- the allowed types and scopes, and how each one renders in the
  release notes
- imperative subjects of at most 72 characters
- a body that explains what changed and why, with guidance per type
- the `Upgrade:` and `BREAKING CHANGE:` footers

Release notes are generated from commit subjects, so every subject
must parse. AGENTS.md links to the section.
---
 AGENTS.md         |   2 +-
 CONTRIBUTING.md   |   2 +-
 docs/agent/dev.md | 132 +++++++++++++++++++++++++++++++++++++++++++---
 3 files changed, 128 insertions(+), 8 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 7d840af6..04803e72 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -83,7 +83,7 @@ Apply to every role, every session.
 3. **Never `git push` without explicit human approval.** Every push, every branch, every time.
 4. **Never commit to `main`.** Feature branches only.
 5. **No `Co-Authored-By:` trailers** in commit messages.
-6. **Semantic commit prefixes:** `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`, `ci:`, `style:`.
+6. **Commit subjects are the changelog.** `<type>(<scope>): <imperative summary>`, then a body that says what and why, in plain technical English. Types, scopes and the `Upgrade:` footer are in [docs/agent/dev.md](docs/agent/dev.md#commits-the-subject-is-the-changelog).
 7. **Never read or copy a user's production family vault.** Reference paths only; fabricate test data.
 8. **Destructive ops need confirmation.** `stack destroy`, `stack uninstall`, `rm -rf`, `git reset --hard`, force-push.
 9. **Announce actions before running them.** No silent long running or integration test runs, scripts, or background commands.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 535394d7..4c94c178 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -69,4 +69,4 @@ A bare `make typecheck` reports on `lib`, `stacklets`, `tools` and `hooks`. `tes
 
 ## Tests, style, commits
 
-All three live in [docs/agent/dev.md](docs/agent/dev.md), which is the canonical reference and stays shorter than a duplicate here would. The short version: `make test-unit` before every commit, module tests over unit tests, semantic commit prefixes, feature branches only, never push without asking.
+All three live in [docs/agent/dev.md](docs/agent/dev.md), which is the canonical reference and stays shorter than a duplicate here would. The short version: `make test-unit` before every commit, module tests over unit tests, feature branches only, never push without asking. Commit subjects are the changelog famstack.dev renders, so they follow `<type>(<scope>): <what the product does now>` and every one has to parse.
diff --git a/docs/agent/dev.md b/docs/agent/dev.md
index 330447b1..09fb7340 100644
--- a/docs/agent/dev.md
+++ b/docs/agent/dev.md
@@ -247,21 +247,140 @@ Testing rules:
 - **Re-read the full error line before calling a failure a duplicate.** Check sender, target, specific IDs. Two errors that look similar at a glance often differ in the load-bearing field.
 - **No backwards-compatibility shims** in pre-1.0 code. Change the code, update callers, ship.
 
-## Commit & branch rules
+## Commits: the subject is the changelog
+
+The release log is the changelog. `stack update` prints it, the GitHub release
+quotes it, famstack.dev renders it. A subject that does not parse is missing
+from the release notes.
+
+Messages follow Conventional Commits and the Git and Linux kernel
+guidelines, in plain technical English.
+
+```
+<type>(<scope>)!: <subject>
+
+<body>
+
+<footer>
+```
+
+`!` marks a change that needs the admin to do something.
+
+| Type | Section | Shown |
+|---|---|---|
+| `feat` | Added | yes |
+| `fix` | Fixed | yes |
+| `security` | Security | yes, near the top |
+| `perf` | Performance | yes |
+| `docs` | Documentation | yes, last |
+| `refactor` `test` `chore` `ci` `style` `build` | | no |
+
+Nothing outside that list. A change that fits none of them is usually two changes.
+
+The scope is what a reader recognises, never a file or a module:
+
+| Scope | Renders as |
+|---|---|
+| `photos` | Photos |
+| `docs`, `archivist` | Documents |
+| `messages` | Messages |
+| `memory`, `wiki`, `curator` | Memory |
+| `agent` | Stacky |
+| `ai` | AI |
+| `chatai` | Chat AI |
+| `code` | Code |
+| `mail` | Email |
+| `backup` | Backup |
+| `core` | Core |
+| `infra` | Networking |
+| `web` | Web |
+| `stack`, `cli`, `doctor`, `update`, `install` | The stack CLI |
+| *(none)* | General |
+
+For type `docs` the scope names the document instead (`docs(readme)`,
+`docs(admin-guide)`, `docs(dev-guide)`), which is why those do not appear
+above. Scoping documentation with a stacklet's name renders it under that
+stacklet, which is how a README fix ends up filed under Documents.
+
+`docs` is both a type and a scope and they mean different things. Type `docs`
+is documentation; scope `docs` is the Documents stacklet. `fix(docs):` changes
+Paperless behaviour; a README fix is `docs(readme):`. A scope outside the
+table still commits and lands under General, so drift surfaces at release time
+rather than on the website.
+
+**Subject rules.** Describe the**Subject.** Imperative mood: it completes "If applied, this commit will
+...". Lowercase after the colon, no full stop, at most 72 characters
+including the prefix. Describe the change as an admin sees it: no class,
+file or function names unless an admin types them. A subject that needs
+"and" is two commits.
+
+**Body.** Blank line after the subject, wrapped at 72. Why the change is
+needed and what it changes; the diff shows how. It must make sense without
+the PR. Bullets for sets of changes. No debugging history, test narrative
+or rhetoric; those go in the PR.
+
+| Type | Body states |
+|---|---|
+| `feat` | what is now possible, how to use it, limits |
+| `fix` | symptom and trigger, cause, fix; `Fixes: <sha> ("<subject>")` if a commit caused it |
+| `perf` | cause, change, before/after numbers and how measured (the only type with measurements) |
+| `refactor` | why, and "No behaviour change." |
+| `docs` `test` `ci` `build` `chore` `style` | what changes and why |
+
+```
+fix(doctor): compare container env with the compose config
+
+`stack doctor` compared a container's environment with the stacklet's
+rendered `.env`, so services that set a different value in compose were
+reported as drifted after every recreate.
+
+Compare with the environment `docker compose config` resolves for the
+service.
+```
+
+he 54 commits in `v0.3.0-beta.2..v0.3.0-beta.3`
+already parse. Both that do not are instructive.
+
+```
+Move the docs stacklet to Paperless-ngx 3.0.4
+```
+
+No type, so it cannot be classified, and it was the most important entry in
+the release: it needed a backup before restarting, and 2.x cannot read the
+database once 3.x has migrated it. Written properly it cannot be lost:
+
+```
+feat(docs)!: move Paperless to 3.0.4
+
+Upgrade: back up ~/famstack-data/docs before restarting the stacklet.
+Paperless migrates the database on first start and 2.x will not read it
+afterwards. There is no downgrade.
+```
+
+| Footer | What it does |
+|---|---|
+| `Upgrade: <what the admin must do>` | Renders as **Action required** at the top of the release. Any update needing a human step: a backup, a config edit, a one-way migration. |
+| `BREAKING CHANGE: <what breaks>` | Same section, for something that breaks an existing setup rather than asking for a step. |
+| `Refs: FAM-12` | Links the tracker card. |
+| `Co-Authored-By:` | Never. Project rule. |
+
+A generator reads the header as
+`^(type)(\((scope)\))?(!)?: (subject)( \(#(pr)\))?$` and groups into **Action
+required** (any `!` or `Upgrade:`), Security, Added, Fixed, Performance,
+Documentation, by rendered scope within each.
+
+## Branch rules
 
 - **Check branch state before major work.** `git fetch origin` and see how the working branch relates to `origin/main` (`git log --oneline origin/main..HEAD` and `HEAD..origin/main`) before starting anything substantial, new branch or existing one alike. The branch may be older than you think: `main` advances, and a local `main` can itself be stale. Branch off (or rebase/merge onto) the latest `origin/main`; a branch left behind silently diverges and lands the PR in merge conflicts.
 - **Feature branches only.** Never commit to `main`.
-- **Semantic prefix required:** `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`, `ci:`, `style:`.
-- **Message style:** short, end-user POV, present tense. *What changed and why a user cares* - not the internal refactor narrative.
-- **No `Co-Authored-By:` trailers.** Project rule.
 - **Commit after every non-trivial fix.** Don't batch at session end. Each commit stands alone for review/revert.
 - **Cascade rule:** if fix N triggers fix N+1 triggers N+2, stop. Name the cascade and propose continue / revert / defer.
 - **Scope drift:** declare it out loud. Silent expansion is forbidden.
 
 ## Pull requests
 
-- PR title: short, semantic-prefix, under 70 chars.
-- PR body: `## Summary` with 1-3 bullets. **No "Test plan" section** - project preference.
+- **One PR is one changelog entry.** Squash merge; the PR title is the commit subject, in the format above, under 70 chars. A PR that needs two changelog lines is two PRs.
+- PR body: `## Summary` with 1-3 bullets, plus any `Upgrade:` / `BREAKING CHANGE:` footer, which lands in the squashed commit where a reviewer can argue with it. **No "Test plan" section** - project preference.
 - **Never `git push` without explicit human approval.** Every push, every branch, every time.
 
 ## Releases
@@ -271,6 +390,7 @@ Pre-tag gate, in order. A published tag is never moved; anything missed here shi
 1. Working tree clean - `git status` shows nothing modified, no stale `uv.lock` (the version bump touches `pyproject.toml` AND the lock; commit them together).
 2. Version bumped in `lib/stack/cli.py` (`VERSION`) and `pyproject.toml`.
 3. Full test round green: framework, stacklets, integration.
+3b. Every commit since the previous tag parses as a changelog entry. An unclassified subject blocks the tag: it would be missing from the release notes and from the website. Reword it if it has not shipped, add the entry by hand if it has.
 4. Fresh-instance install verified.
 5. Stale references updated: README version callouts, docs links, blog "Try it" instructions.
 6. Tag (`vX.Y.Z` / `vX.Y.Z-beta.N`, annotated), push main + tag, publish the GitHub release with Highlights and an "Upgrading from" section.

From 7471471bb5598c850972e051fecba61acc49c320 Mon Sep 17 00:00:00 2001
From: Arthur <hello@arthware.dev>
Date: Sun, 20 Sep 2026 15:29:38 +0200
Subject: [PATCH 02/11] ci: validate commit subjects against the changelog
 format

Add `tools/commit-lint`, which checks commit headers against the format
in docs/agent/dev.md. It runs in:

- the `commit-msg` hook
- CI, on the PR title and on every commit in the PR
- the release gate, on the range being tagged

Scopes are only checked for types that appear in the changelog. CI
prints the number of checked subjects and fails on an empty range. A
test verifies that the type and scope lists match dev.md.

Scopes are now stacklet ids and bot names, rendered as "<id> Stacklet"
and "<name> Bot".
---
 .github/workflows/ci.yml            |  18 ++-
 CONTRIBUTING.md                     |   6 +
 docs/agent/dev.md                   |  62 +++++---
 hooks/commit-msg                    |  14 ++
 tests/framework/test_commit_lint.py | 198 ++++++++++++++++++++++++
 tools/commit-lint                   | 223 ++++++++++++++++++++++++++++
 6 files changed, 499 insertions(+), 22 deletions(-)
 create mode 100755 hooks/commit-msg
 create mode 100644 tests/framework/test_commit_lint.py
 create mode 100755 tools/commit-lint

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cd26af43..28d4588d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,5 +1,6 @@
 # Tier 1 of the release gate (docs/agent/dev.md, "Releases"): the checks
-# that need no Docker and no macOS. Runs on every push/PR; on version
+# that need no Docker and no macOS, including that every commit subject
+# parses as a changelog entry. Runs on every push/PR; on version
 # tags it additionally enforces that the tag, the CLI VERSION, and
 # pyproject.toml all agree. Tiers 2 (integration suite) and 3 (fresh
 # install, ai stacklet) stay manual — see docs/cleanup-backlog.md.
@@ -61,6 +62,21 @@ jobs:
           print("Versions agree:", ", ".join(f"{s}={v}" for s, v in versions.items()))
           EOF
 
+      - name: Commit convention
+        # The changelog is generated from these subjects, so one that
+        # does not parse is an entry missing from the release notes.
+        # Squash merging makes the PR title the subject that lands, so
+        # it is checked too.
+        if: github.event_name == 'pull_request'
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          BASE: ${{ github.event.pull_request.base.sha }}
+          HEAD: ${{ github.event.pull_request.head.sha }}
+        run: |
+          git fetch --no-tags --depth=50 origin "$BASE" "$HEAD" 2>/dev/null || true
+          python3 tools/commit-lint --title "$PR_TITLE"
+          python3 tools/commit-lint --range "$BASE..$HEAD"
+
       - name: Framework tests
         run: uv run --extra test pytest tests/framework/ --ignore=tests/framework/test_config_to_container.py -q
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4c94c178..c73a97a2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -70,3 +70,9 @@ A bare `make typecheck` reports on `lib`, `stacklets`, `tools` and `hooks`. `tes
 ## Tests, style, commits
 
 All three live in [docs/agent/dev.md](docs/agent/dev.md), which is the canonical reference and stays shorter than a duplicate here would. The short version: `make test-unit` before every commit, module tests over unit tests, feature branches only, never push without asking. Commit subjects are the changelog famstack.dev renders, so they follow `<type>(<scope>): <what the product does now>` and every one has to parse.
+
+Enable the hooks once per clone so lint and the commit convention are checked before a commit exists rather than in CI:
+
+```bash
+git config core.hooksPath hooks
+```
diff --git a/docs/agent/dev.md b/docs/agent/dev.md
index 09fb7340..11eca5ae 100644
--- a/docs/agent/dev.md
+++ b/docs/agent/dev.md
@@ -281,26 +281,34 @@ The scope is what a reader recognises, never a file or a module:
 
 | Scope | Renders as |
 |---|---|
-| `photos` | Photos |
-| `docs`, `archivist` | Documents |
-| `messages` | Messages |
-| `memory`, `wiki`, `curator` | Memory |
-| `agent` | Stacky |
-| `ai` | AI |
-| `chatai` | Chat AI |
-| `code` | Code |
-| `mail` | Email |
-| `backup` | Backup |
-| `core` | Core |
-| `infra` | Networking |
-| `web` | Web |
-| `stack`, `cli`, `doctor`, `update`, `install` | The stack CLI |
+| `agent` | Agent Stacklet |
+| `ai` | AI Stacklet |
+| `backup` | Backup Stacklet |
+| `chatai` | ChatAI Stacklet |
+| `code` | Code Stacklet |
+| `core` | Core Stacklet |
+| `docs` | Docs Stacklet |
+| `infra` | Infra Stacklet |
+| `memory` | Memory Stacklet |
+| `messages` | Messages Stacklet |
+| `photos` | Photos Stacklet |
+| `archivist` | Archivist Bot |
+| `mail` | Mail Bot |
+| `scribe` | Scribe Bot |
+| `stacker` | Stacker Bot |
+| `curator`, `wiki` | Memory Stacklet |
+| `stack`, `cli`, `doctor`, `update`, `install` | stack CLI |
+| `web` | web fetch |
 | *(none)* | General |
 
-For type `docs` the scope names the document instead (`docs(readme)`,
-`docs(admin-guide)`, `docs(dev-guide)`), which is why those do not appear
-above. Scoping documentation with a stacklet's name renders it under that
-stacklet, which is how a README fix ends up filed under Documents.
+The scope is a stacklet id or a bot name, written the way the code writes
+it, so a reader can go from a changelog line to the directory it came from.
+A stacklet renders as "<id> Stacklet" and a bot as "<name> Bot": one release
+line saying "Archivist Bot" and the next saying "Docs Stacklet" tells you
+which one changed without opening anything.
+
+Anything that is neither, a component like the wiki or the curator, renders
+as the stacklet that owns it.
 
 `docs` is both a type and a scope and they mean different things. Type `docs`
 is documentation; scope `docs` is the Documents stacklet. `fix(docs):` changes
@@ -352,11 +360,17 @@ database once 3.x has migrated it. Written properly it cannot be lost:
 ```
 feat(docs)!: move Paperless to 3.0.4
 
-Upgrade: back up ~/famstack-data/docs before restarting the stacklet.
-Paperless migrates the database on first start and 2.x will not read it
-afterwards. There is no downgrade.
+Upgrade: back up `~/famstack-data/docs` before restarting the stacklet
+with `./stack restart docs`. Paperless migrates the database on first
+start and 2.x will not read it afterwards. There is no downgrade.
 ```
 
+**The body is markdown.** It is quoted verbatim into the GitHub release
+and rendered on famstack.dev, so commands and paths in it are written as
+code: `` `./stack restart docs` ``, `` `~/famstack-data/docs` ``. The
+subject is not: it appears in plain-text contexts too, including
+`./stack update` output, where backticks would be literal clutter.
+
 | Footer | What it does |
 |---|---|
 | `Upgrade: <what the admin must do>` | Renders as **Action required** at the top of the release. Any update needing a human step: a backup, a config edit, a one-way migration. |
@@ -364,6 +378,12 @@ afterwards. There is no downgrade.
 | `Refs: FAM-12` | Links the tracker card. |
 | `Co-Authored-By:` | Never. Project rule. |
 
+`tools/commit-lint` enforces the header, and is the same check in every
+place that matters: the `commit-msg` hook rejects it before the commit
+exists, CI rejects the PR title and every commit in the PR, and the
+release gate runs it over the range being tagged. Enable the hooks once
+per clone with `git config core.hooksPath hooks`.
+
 A generator reads the header as
 `^(type)(\((scope)\))?(!)?: (subject)( \(#(pr)\))?$` and groups into **Action
 required** (any `!` or `Upgrade:`), Security, Added, Fixed, Performance,
diff --git a/hooks/commit-msg b/hooks/commit-msg
new file mode 100755
index 00000000..6871a8db
--- /dev/null
+++ b/hooks/commit-msg
@@ -0,0 +1,14 @@
+#!/bin/sh
+# Block commit subjects that would not parse as a changelog entry.
+#
+# Enable once per clone (same switch as the pre-commit hook):
+#     git config core.hooksPath hooks
+#
+# The release log is the changelog, so a subject that does not parse is
+# an entry missing from what the world reads. Same rules as CI, so a
+# commit that passes here passes there.
+
+if ! python3 tools/commit-lint --message "$1"; then
+    echo "  Fix the subject, or commit with --no-verify to bypass." >&2
+    exit 1
+fi
diff --git a/tests/framework/test_commit_lint.py b/tests/framework/test_commit_lint.py
new file mode 100644
index 00000000..c9ae905e
--- /dev/null
+++ b/tests/framework/test_commit_lint.py
@@ -0,0 +1,198 @@
+"""The guard that keeps commit subjects parseable as changelog entries.
+
+The convention is only worth writing down if it is checked the same way
+every time, by the hook before a commit exists and by CI before it
+merges. These pin the rules, and one of them pins the rules against the
+document that explains them, because that pair has already drifted once:
+the table in dev.md was missing the scope seven commits already used.
+"""
+
+import importlib.machinery
+import importlib.util
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+
+# The tool has no .py extension, matching tools/branch-status, so it is
+# loaded by path rather than imported.
+_spec = importlib.util.spec_from_loader(
+    "commit_lint",
+    importlib.machinery.SourceFileLoader(
+        "commit_lint", str(REPO_ROOT / "tools" / "commit-lint")),
+)
+commit_lint = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(commit_lint)
+
+
+# ── The rules ────────────────────────────────────────────────────────────
+
+class TestSubjectsThatPass:
+
+    @pytest.mark.parametrize("subject", [
+        "fix(archivist): stop filing your conversations, keep what you pin",
+        "feat(memory): ask the family vault a question in plain words",
+        "docs: write down how commits and PRs become the changelog",
+        "docs(readme): stop announcing an old release as current",
+        "feat(docs)!: move Paperless to 3.0.4",
+        "chore(release): v0.3.0-beta.4",
+        "fix(ai): install the local AI engine on current Homebrew (#72)",
+    ])
+    def test_real_subjects_from_the_history(self, subject):
+        assert commit_lint.check(subject) == []
+
+    @pytest.mark.parametrize("subject", [
+        "Merge branch 'main' into feat/x",
+        'Revert "feat(photos): something"',
+        "fixup! fix(core): something",
+    ])
+    def test_git_writes_these_itself(self, subject):
+        """Linting them teaches people to pass --no-verify, nothing else."""
+        assert commit_lint.check(subject) == []
+
+
+class TestSubjectsThatFail:
+
+    def test_no_type_at_all(self):
+        """The real one: the Paperless 3.0.4 move, the most important entry
+        in its release, unclassifiable and so missing from the changelog."""
+        problems = commit_lint.check("Move the docs stacklet to Paperless-ngx 3.0.4")
+        assert any("does not parse" in p for p in problems)
+
+    def test_a_type_nobody_agreed_on(self):
+        problems = commit_lint.check("improvement(photos): make it faster")
+        assert problems
+
+    def test_a_scope_that_renders_nowhere(self):
+        problems = commit_lint.check("fix(archivist-bot): file a document once")
+        assert any("not a scope" in p for p in problems)
+
+    def test_documentation_scopes_name_the_document(self):
+        """`docs(dev-guide)` is right and `fix(dev-guide)` is not: only
+        documentation is scoped by document."""
+        assert commit_lint.check("docs(dev-guide): explain the release gate") == []
+        assert commit_lint.check("fix(dev-guide): explain the release gate")
+
+    def test_too_long_to_read_in_a_list(self):
+        subject = "fix(core): " + "x" * 80
+        assert any("limit is 72" in p for p in commit_lint.check(subject))
+
+    def test_written_as_a_title(self):
+        problems = commit_lint.check("feat(photos): Stop the upload stalling")
+        assert any("capital" in p for p in problems)
+
+    def test_ends_with_a_full_stop(self):
+        problems = commit_lint.check("feat(photos): stop the upload stalling.")
+        assert any("full stop" in p for p in problems)
+
+
+# ── The guard against the document drifting ──────────────────────────────
+
+class TestRulesMatchTheDocumentation:
+    """dev.md explains the rules to a person; this script enforces them.
+
+    Two copies of one list is a drift waiting to happen, and it already
+    happened: `stack` was used by seven commits before the table admitted
+    it existed.
+    """
+
+    def _table_terms(self, heading: str) -> set[str]:
+        """Backticked terms in the first column of the table under a heading."""
+        text = (REPO_ROOT / "docs" / "agent" / "dev.md").read_text()
+        section = text.split(heading, 1)[1]
+        terms = set()
+        for line in section.splitlines():
+            if not line.startswith("|") or line.startswith("|---"):
+                continue
+            first = line.split("|")[1]
+            found = re.findall(r"`([a-z0-9-]+)`", first)
+            if not found:
+                break  # past the table
+            terms.update(found)
+        return terms
+
+    def test_every_documented_type_is_accepted(self):
+        documented = self._table_terms("| Type | Section | Shown |")
+        assert documented, "the types table moved or changed shape"
+        assert documented == set(commit_lint.TYPES)
+
+    def test_every_documented_scope_is_accepted(self):
+        documented = self._table_terms("| Scope | Renders as |")
+        assert documented, "the scopes table moved or changed shape"
+        assert documented == set(commit_lint.SCOPES)
+
+
+# ── The surfaces ─────────────────────────────────────────────────────────
+
+class TestCommandLine:
+    """Three ways in, because a hook has a file, CI has a range and a
+    title, and the release gate has a range."""
+
+    def _run(self, *args, cwd=None):
+        return subprocess.run(
+            [sys.executable, str(REPO_ROOT / "tools" / "commit-lint"), *args],
+            capture_output=True, text=True, cwd=cwd or REPO_ROOT,
+        )
+
+    @pytest.fixture
+    def three_commits(self, tmp_path):
+        """A repository of known depth.
+
+        Reading this repo's own history fails wherever the checkout is
+        shallow, which is every CI run: `HEAD~3` does not resolve at
+        depth 1. A range test that depends on ambient history is a test
+        that passes on a laptop and fails on a runner.
+        """
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        subprocess.run(["git", "init", "-q", str(repo)], check=True)
+        for name, subject in [("a", "feat(photos): back up over Wi-Fi"),
+                              ("b", "fix(core): answer the first message"),
+                              ("c", "docs: explain the release gate")]:
+            (repo / name).write_text(name)
+            subprocess.run(["git", "-C", str(repo), "add", "-A"], check=True)
+            subprocess.run(["git", "-C", str(repo), "-c", "user.email=t@example.com",
+                            "-c", "user.name=T", "commit", "-qm", subject], check=True)
+        return repo
+
+    def test_a_good_title_exits_zero(self):
+        assert self._run("--title", "fix(core): answer the first message").returncode == 0
+
+    def test_a_bad_title_exits_one_and_says_why(self):
+        result = self._run("--title", "made it better")
+        assert result.returncode == 1
+        assert "does not parse" in result.stderr
+
+    def test_a_range_says_what_it_checked(self, three_commits):
+        result = self._run("--range", "HEAD~2..HEAD", cwd=three_commits)
+
+        assert result.returncode == 0, result.stderr
+        assert "2 subject(s) checked" in result.stdout
+
+    def test_an_empty_range_is_a_failure_not_a_pass(self, three_commits):
+        """How this guard dies quietly: a shallow checkout leaves nothing
+        to read and the step goes green having checked nothing."""
+        result = self._run("--range", "HEAD..HEAD", cwd=three_commits)
+
+        assert result.returncode == 1
+        assert "no commits" in result.stderr
+
+    def test_a_message_file(self, tmp_path):
+        message = tmp_path / "COMMIT_EDITMSG"
+        message.write_text("feat(photos): back up from the phone over Wi-Fi\n\nbody\n")
+        assert self._run("--message", str(message)).returncode == 0
+
+    def test_only_the_first_line_of_a_message_is_the_subject(self, tmp_path):
+        """Bodies hold prose, footers and quoted output. None of it is
+        the changelog line, so none of it is linted."""
+        message = tmp_path / "COMMIT_EDITMSG"
+        message.write_text(
+            "fix(memory): keep the vault syncing after the Mac changes IP\n\n"
+            "Upgrade: nothing to do.\n"
+            "A body line that would never pass as a subject.\n"
+        )
+        assert self._run("--message", str(message)).returncode == 0
diff --git a/tools/commit-lint b/tools/commit-lint
new file mode 100755
index 00000000..ac29df5e
--- /dev/null
+++ b/tools/commit-lint
@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""Check that commit subjects parse as changelog entries.
+
+The release log is the changelog (docs/agent/dev.md, "Commits: the
+subject is the changelog"), which only works if every subject parses.
+This is the deterministic half of that: the same rules, applied the same
+way, by a hook before the commit exists and by CI before it merges.
+
+Three ways in, one rule set:
+
+    tools/commit-lint --message .git/COMMIT_EDITMSG   one message, for the hook
+    tools/commit-lint --range origin/main..HEAD       a range, for CI and releases
+    tools/commit-lint --title "feat(photos): ..."     a PR title, which squash
+                                                      merging turns into a subject
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+
+# Types, and where each one lands in the changelog. The empty string
+# means it is not shown; internal work is still committed, just not
+# announced.
+TYPES = {
+    "feat": "Added",
+    "fix": "Fixed",
+    "security": "Security",
+    "perf": "Performance",
+    "docs": "Documentation",
+    "refactor": "",
+    "test": "",
+    "chore": "",
+    "ci": "",
+    "style": "",
+    "build": "",
+}
+
+# Scopes, and what a reader sees. Keep in step with the table in
+# docs/agent/dev.md; a test asserts the two agree.
+SCOPES = {
+    # Stacklets, by the id the directory and the CLI use.
+    "agent": "Agent Stacklet",
+    "ai": "AI Stacklet",
+    "backup": "Backup Stacklet",
+    "chatai": "ChatAI Stacklet",
+    "code": "Code Stacklet",
+    "core": "Core Stacklet",
+    "docs": "Docs Stacklet",
+    "infra": "Infra Stacklet",
+    "memory": "Memory Stacklet",
+    "messages": "Messages Stacklet",
+    "photos": "Photos Stacklet",
+    # Bots, by the name in their bot.toml with the -bot suffix dropped.
+    "archivist": "Archivist Bot",
+    "mail": "Mail Bot",
+    "scribe": "Scribe Bot",
+    "stacker": "Stacker Bot",
+    # Components that are neither: the stacklet that owns them.
+    "curator": "Memory Stacklet",
+    "wiki": "Memory Stacklet",
+    # The framework itself.
+    "stack": "stack CLI",
+    "cli": "stack CLI",
+    "doctor": "stack CLI",
+    "update": "stack CLI",
+    "install": "stack CLI",
+    "web": "web fetch",
+}
+
+
+SUBJECT_LIMIT = 72
+
+HEADER = re.compile(
+    r"^(?P<type>[a-z]+)"
+    r"(?:\((?P<scope>[a-z0-9-]+)\))?"
+    r"(?P<breaking>!)?"
+    r": (?P<subject>.+?)"
+    r"(?: \(#(?P<pr>\d+)\))?$"
+)
+
+# Git writes these itself, or they are machine-made and never reach a
+# changelog. Linting them would only teach people to pass --no-verify.
+EXEMPT = re.compile(r"^(Merge |Revert \"|fixup! |squash! |Bumps )")
+
+
+def check(header: str) -> list[str]:
+    """Every rule this subject breaks, in the order a reader would fix them."""
+    header = header.rstrip()
+    if not header or EXEMPT.match(header):
+        return []
+
+    match = HEADER.match(header)
+    if not match:
+        return [
+            "does not parse as <type>(<scope>): <subject>",
+            f"  types: {', '.join(sorted(TYPES))}",
+            "  example: fix(photos): stop the upload stalling on a slow phone",
+        ]
+
+    problems = []
+    kind, scope, subject = match["type"], match["scope"], match["subject"]
+
+    if kind not in TYPES:
+        problems.append(
+            f"'{kind}' is not a type. Use one of: {', '.join(sorted(TYPES))}")
+
+    # A scope exists to group entries in the changelog, so it is only
+    # checked for types that appear there. `chore(release)` and
+    # `test(stack)` name something useful to a developer and nothing to a
+    # reader, and policing them would be bureaucracy.
+    #
+    # Documentation is shown but scoped by document rather than by
+    # stacklet, so docs(readme) and docs(admin-guide) are fine.
+    groups_by_scope = bool(TYPES.get(kind)) and kind != "docs"
+    if scope and groups_by_scope and scope not in SCOPES:
+        problems.append(
+            f"'{scope}' is not a scope. Use one of: {', '.join(sorted(SCOPES))}"
+            " (or no scope at all)")
+
+    if len(header) > SUBJECT_LIMIT:
+        problems.append(
+            f"{len(header)} characters, limit is {SUBJECT_LIMIT}")
+
+    if subject[:1].isupper():
+        problems.append("starts with a capital; the subject is a sentence "
+                        "fragment, not a title")
+
+    if subject.endswith("."):
+        problems.append("ends with a full stop")
+
+    return problems
+
+
+def say(message: str, err: bool = False) -> None:
+    print(message, file=sys.stderr if err else sys.stdout, flush=True)
+
+
+def report(header: str, problems: list[str], where: str = "") -> None:
+    location = f"{where}  " if where else ""
+    print(f"\n  ✗ {location}{header}", file=sys.stderr)
+    for problem in problems:
+        print(f"      {problem}", file=sys.stderr)
+
+
+def subjects_in(rev_range: str) -> list[tuple[str, str]]:
+    """Subjects in a range, read from the repository you are standing in.
+
+    Not from the repository this script lives in: those are the same
+    thing in normal use, and letting the caller choose means a release
+    script, or a test, can point it at another checkout.
+    """
+    result = subprocess.run(
+        ["git", "log", "--no-merges", "--format=%h%x00%s", rev_range],
+        capture_output=True, text=True,
+    )
+    if result.returncode != 0:
+        print(result.stderr.strip(), file=sys.stderr)
+        sys.exit(2)
+    pairs = []
+    for line in result.stdout.splitlines():
+        if line.strip():
+            sha, _, subject = line.partition("\0")
+            pairs.append((sha, subject))
+    return pairs
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--message", help="File holding one commit message")
+    source.add_argument("--range", help="Revision range, e.g. origin/main..HEAD")
+    source.add_argument("--title", help="A pull request title")
+    args = parser.parse_args()
+
+    failures = 0
+
+    if args.message:
+        with open(args.message, encoding="utf-8") as f:
+            header = f.readline()
+        problems = check(header)
+        if problems:
+            report(header.rstrip(), problems)
+            failures = 1
+
+    elif args.title:
+        problems = check(args.title)
+        if problems:
+            report(args.title, problems)
+            failures = 1
+
+    else:
+        # An empty range is how this guard dies quietly: a shallow clone
+        # or a bad base leaves nothing to check and the step goes green
+        # having read nothing. Say what was checked, and refuse to pass
+        # on nothing.
+        pairs = subjects_in(args.range)
+        if not pairs:
+            say(f"\n  \u2717 no commits in {args.range}", err=True)
+            say("      Nothing was checked. A shallow checkout or a wrong "
+                "base makes this guard pass blind.", err=True)
+            return 1
+        for sha, subject in pairs:
+            problems = check(subject)
+            if problems:
+                report(subject, problems, where=sha)
+                failures += 1
+        if not failures:
+            say(f"  {len(pairs)} subject(s) checked, all parse")
+
+    if failures:
+        print(f"\n  {failures} subject(s) to fix. The rules and the reasoning:"
+              f"\n  docs/agent/dev.md, \"Commits: the subject is the changelog\"\n",
+              file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From 10129b7fc5c1d07f52652bc1a047ba9447d216ce Mon Sep 17 00:00:00 2001
From: Arthur <hello@arthware.dev>
Date: Sun, 20 Sep 2026 09:14:19 +0200
Subject: [PATCH 03/11] feat(stack): load stacklets from extension directories

Add `[core] extension_dirs`, a list of directories that are searched
after `stacklets/` for stacklets that do not ship with the release. The
default is `~/famstack-extensions`. The directory is not created
automatically, and configured paths that do not exist are skipped.

- Hooks, CLI plugins, secrets and env templates work the same way as
  for built-in stacklets. On an id clash the repo wins, then the first
  extension directory in the list.
- Add a `stage` manifest field (`beta`, `incubating`). `stack list`
  shows it and `stack up` prints a warning.
- `stack list` and `stack status` show extensions in a separate section,
  including the directory each one was loaded from.
- The bot runner mounts the first extension directory. `stack up` warns
  when a stacklet in another directory ships a bot.

Extensions are kept outside the repo and the data dir because the repo
is replaced on update and the data dir is deleted by `stack uninstall`.
They are not covered by the backup instructions for `~/famstack-data`.
---
 .gitignore                                    |   5 +
 .../adr-013-stacklet-locations-and-stages.md  | 114 ++++++
 docs/agent/dev.md                             |   3 +
 docs/agent/ops.md                             |   5 +-
 docs/creating-stacklets.md                    |  42 ++-
 docs/design-notes.md                          |  21 ++
 docs/stack-reference.md                       |  33 +-
 lib/stack/cli.py                              |  50 ++-
 lib/stack/prompt.py                           |  26 +-
 lib/stack/stack.py                            | 205 +++++++++--
 stack.example.toml                            |  19 +
 stacklets/core/bot-runner/main.py             |  24 +-
 stacklets/core/docker-compose.yml             |   4 +
 stacklets/core/hooks/on_start.py              |   7 +
 stacklets/core/stacklet.toml                  |   6 +
 tests/framework/conftest.py                   |  10 +-
 .../fixtures/guest/docker-compose.yml         |  31 ++
 .../fixtures/guest/hooks/on_install.py        |  14 +
 tests/framework/fixtures/guest/stacklet.toml  |  27 ++
 .../fixtures/incubating/stacklet.toml         |  13 +
 tests/framework/test_config_to_container.py   | 139 ++++++++
 tests/framework/test_extensions.py            | 330 ++++++++++++++++++
 22 files changed, 1086 insertions(+), 42 deletions(-)
 create mode 100644 docs/adr/adr-013-stacklet-locations-and-stages.md
 create mode 100644 tests/framework/fixtures/guest/docker-compose.yml
 create mode 100644 tests/framework/fixtures/guest/hooks/on_install.py
 create mode 100644 tests/framework/fixtures/guest/stacklet.toml
 create mode 100644 tests/framework/fixtures/incubating/stacklet.toml
 create mode 100644 tests/framework/test_extensions.py

diff --git a/.gitignore b/.gitignore
index 2c637ded..cdc6a04e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -56,6 +56,11 @@ tests/integration/eval/runs/
 .claude/skills/*
 !.claude/skills/famstack-lsp/
 
+# Extension stacklets live in ~/<product>-extensions, not here. This is
+# the obvious place to try anyway, so keep anything dropped here out of
+# git rather than in someone's next commit.
+/extensions/
+
 # Internal development notes
 impl/
 
diff --git a/docs/adr/adr-013-stacklet-locations-and-stages.md b/docs/adr/adr-013-stacklet-locations-and-stages.md
new file mode 100644
index 00000000..aff53e47
--- /dev/null
+++ b/docs/adr/adr-013-stacklet-locations-and-stages.md
@@ -0,0 +1,114 @@
+# ADR-013: Stacklet Locations and Stages
+
+## Status
+Accepted
+
+## Context
+A stacklet was "a directory with a `stacklet.toml` under `stacklets/`". One
+location, one git repo, one release. Everything that did not fit that shape
+needed a workaround: a `.git/info/exclude` entry for a stacklet that was not
+meant to be public, a long-lived branch for one that was not finished. Both
+grow stale, and neither survives a rebase of `main`.
+
+Three kinds of stacklet do not belong in `stacklets/`:
+
+- **Private.** Written for one household or one office, not for the project.
+- **Third-party.** Someone else's stacklet, with its own repo and release cycle.
+- **Unfinished.** Ours, but not ready to be presented as part of a release.
+
+The first two are a question of location. The third is orthogonal: a stacklet
+in either location can be half-built, and an operator who starts one deserves
+to be told before the containers come up, not after their family is using it.
+
+Alternatives considered for location:
+
+- **Keep one directory, gate with git.** What we were doing. A
+  `.git/info/exclude` entry is local and invisible to everyone else, and a
+  branch that carries a stacklet has to be rebased forever.
+- **A directory under `data_dir`.** It would be covered by the one backup the
+  admin guide mandates, and `stack uninstall` would clear it out with
+  everything else. Rejected: `~/famstack-data/<id>/` is what running services
+  write, and a stacklet is source code. Putting code there also makes
+  `extensions` a reserved stacklet id.
+- **`extensions/` inside the repo, beside `stacklets/`.** The most legible
+  option, and the one that reads best in the tree. Rejected: it only works
+  because today's install method is "clone a git repo". The repo is what an
+  upgrade replaces, so a location inside it is a promise we can only keep
+  while that stays true, and defaults are sticky long after.
+
+The three populations this serves do not want the same thing. An incubating
+stacklet of ours is disposable and wants to be near the repo; a household's
+own stacklet must outlive every reinstall; a third-party one wants an
+installer and a trust boundary. Only the first exists today, but a default is
+picked once, so it is picked for the one with the strictest requirement.
+- **Install by URL** (`stack extensions add <git-url>`). Useful later, and it
+  only makes sense once a second location exists at all.
+
+## Decision
+Discovery searches the repo's `stacklets/` first, then every directory in
+`[core] extension_dirs`, in the order given. That key is a list and defaults
+to `["~/<product>-extensions"]`, so `~/famstack-extensions` on a famstack
+instance; a bare string is read as a one-entry list. A directory with a
+`stacklet.toml` is a stacklet in any of them.
+
+Nothing creates that directory. An admin who has no extensions has no such
+directory, and discovery skips a configured path that is not there. It is
+outside both the repo and the data dir on purpose: the repo is replaced on
+upgrade, and the data dir is what running services write.
+
+The first tree to claim an `id` keeps it. The repo therefore wins a clash with
+an extension, and an earlier extension dir wins a clash with a later one, the
+way a `PATH` resolves. An extension can add a stacklet, never replace one the
+release ships.
+
+Everything downstream resolves a stacklet by `id` rather than by path, so
+hooks, CLI plugins, secrets, `{photos_url}`-style template variables and
+`stack up <id>` work identically wherever it lives. Origin is reported rather
+than inferred: every stacklet carries `source` (`repo` or `extension`) and
+`path` through `discover`, `list`, `status` and `up`, `list`/`status` also
+report `extension_dirs`, and both printers group extensions under their own
+heading instead of mixing them into one column.
+
+The bot runner gets a second read-only bind mount,
+`${EXTENSIONS_DIR}:/extensions:ro`, and searches both trees in the runtime's
+order, so an extension stacklet can ship a bot. A compose file cannot iterate
+a list, so exactly one extension dir is mounted: the first. A stacklet that
+ships a bot from any other one would fail silently, so `stack up` says so.
+
+A bind mount needs its source to exist, which collides with creating nothing.
+While the mounted dir is absent the mount source resolves to an empty
+stand-in, `.stack/no-extensions`, and core's `on_start` creates whichever of
+the two applies. Any `stack up` re-renders core's env, so the real directory
+takes over on its own once there is one.
+
+A manifest declares how finished it is with `stage`. The default is `"stable"`
+and is silent. Any other value is repeated back: `stack list` marks it, and
+every `stack up` warns that the stacklet can change or disappear and is not
+for production. `"beta"` and `"incubating"` have their own wording; an
+unrecognised value gets a generic warning rather than a validation error,
+because the manifest is making a claim and the runtime's job is to pass it on.
+
+## Consequences
+- A private or incubating stacklet needs no ignore rule and no branch. It is
+  not in the repo at all, so `git status` never sees it and it can be its own
+  git repo.
+- A second directory is a search path, not a full second home: its stacklets
+  install, run and get CLI plugins, but a bot there is invisible to the runner
+  until the directory is first in the list. Mounting all of them needs a
+  generated compose override, which is a framework change and its own decision.
+- An extension now survives everything famstack does: upgrade, `stack
+  uninstall`, a fresh clone elsewhere. Nothing backs it up either. The backup
+  section of the operator docs lists it, and an extension that matters should
+  have a git remote.
+- An admin who would rather keep it elsewhere, including inside the data dir,
+  points `extension_dirs` there. The uninstall prompt names any extension dir
+  it is about to delete.
+- The default is derived from `[core] name`, so an instance that renames the
+  stack reads `~/<that name>-extensions`. The framework stays domain-agnostic;
+  nothing in `lib/stack/` spells "famstack".
+- The install wizard still scans only the repo. Extensions are installed after
+  setup, with `stack up <id>`.
+- Symlinking a stacklet into the extensions dir works for discovery and hooks,
+  but not for a bot: the bind mount exposes the link, not its target.
+- `stack extensions add <git-url>` becomes possible later without another
+  decision. It would clone into this directory and pin a commit.
diff --git a/docs/agent/dev.md b/docs/agent/dev.md
index 11eca5ae..1da268bc 100644
--- a/docs/agent/dev.md
+++ b/docs/agent/dev.md
@@ -89,6 +89,8 @@ Optional, all convention-named:
 
 ### Stacklet rules
 
+- **Location.** `stacklets/<id>/` is for what the release ships. A private, incubating or third-party stacklet goes in `~/<product>-extensions/` (`[core] extension_dirs` adds more search paths) and is discovered the same way, bot included. Searched in order, first claim on an id wins, and only the first dir is mounted into the bot runner.
+- **`stage`.** Anything not finished declares `stage = "beta"` or `"incubating"`. `stack list` marks it, `stack up` warns.
 - **`id` == directory name.** Lowercase, no hyphens, no spaces. Used in container names, env namespacing, secret keys.
 - **Container name:** `stack-<id>` (single-service) or `stack-<id>-<service>` (multi). Set both `services.<key>` and `container_name`.
 - **Network:** every container joins the `stack` network, declared `external: true`. Cross-stacklet refs go by container name (`http://stack-docs-paperless:8000`).
@@ -446,3 +448,4 @@ Read the relevant ADR before touching the pillar it describes.
 | [adr-007](../adr/adr-007-port-convention.md) | 42xxx port convention |
 | [adr-008](../adr/adr-008-convention-based-bot-runner.md) | Convention-based bot runner |
 | [adr-009](../adr/adr-009-managed-ai-provider.md) | Managed AI provider |
+| [adr-013](../adr/adr-013-stacklet-locations-and-stages.md) | Stacklet locations and stages |
diff --git a/docs/agent/ops.md b/docs/agent/ops.md
index a4b2c30f..c51c9730 100644
--- a/docs/agent/ops.md
+++ b/docs/agent/ops.md
@@ -10,7 +10,7 @@ the compact decision layer; the admin guide is the manual.
 ## Mental model in 3 lines
 
 1. `stack.toml` (per-host config) + each stacklet's `stacklet.toml` → render `.env` on every `stack up`. `.env` is **derived**, never edit it.
-2. Every stacklet lives under `stacklets/<id>/`. All persistent data lives under `~/famstack-data/<id>/`. No exceptions.
+2. Every stacklet lives under `stacklets/<id>/`, or under `~/famstack-extensions/<id>/` if it does not ship with famstack. All persistent data lives under `~/famstack-data/<id>/`. No exceptions.
 3. State is **derived**, not stored. Container existence == "running"; container absence + data dir absence == "available". There is no enabled-list.
 
 ## Hardware preconditions
@@ -54,6 +54,8 @@ If a precondition is missing, `./stack` prints exactly what to do. Don't improvi
 - `.stack/secrets.toml` is **gitignored** and contains generated passwords + tokens. Treat as a password export.
 - Data lives **outside the repo** at `~/famstack-data/<id>/`. That's the only mandatory backup.
 - `~/.omlx/models/` holds LLM model files. Re-downloadable; not in `data_dir`.
+- **Extension stacklets are source code, and nothing backs them up.** `~/famstack-extensions/<id>/` holds stacklets famstack does not ship. Nothing creates it, nothing deletes it, and it is outside the data dir the backup rule covers. Push it to a remote. `[core] extension_dirs` (a list, first entry wins a clash and is the one mounted into the bot runner) adds or moves search paths.
+- **A stage is a claim, not a fault.** `stack list` and `stack status` group extensions in their own section and show a stage that is not stable. The warning on `stack up` means the stacklet can change or disappear between releases. Do not put anything irreplaceable in it.
 - **Two famstack instances cannot run on the same Mac at the same time** - container names collide (`stack-<id>`). `stack down` the active one first.
 
 ## Danger zones
@@ -115,6 +117,7 @@ For symptoms not on this table: `./stack logs <id>` + `./stack errors`, paste ou
   ```bash
   tar czf famstack-config-$(date +%F).tgz stack.toml users.toml .stack/
   ```
+- **`~/famstack-extensions/`** - only if the instance has one. Source code for stacklets famstack does not ship; a git remote counts.
 - **`~/.omlx/models/`** - re-downloadable; skip.
 
 ## Boundaries
diff --git a/docs/creating-stacklets.md b/docs/creating-stacklets.md
index 3a0c95bf..c515cf82 100644
--- a/docs/creating-stacklets.md
+++ b/docs/creating-stacklets.md
@@ -1,6 +1,6 @@
 # Creating a Stacklet
 
-A stacklet is a self-contained service unit. It's a directory under `stacklets/` with a manifest, a Docker Compose file, and optional hooks.
+A stacklet is a self-contained service unit. It's a directory with a manifest, a Docker Compose file, and optional hooks.
 
 ## Minimal stacklet
 
@@ -12,6 +12,46 @@ stacklets/myapp/
 
 That's it. Two files and `stack up myapp` works.
 
+## Where it lives
+
+`stacklets/` holds the stacklets famstack ships. Everything else goes in
+`~/famstack-extensions/`, or wherever `[core] extension_dirs` points:
+
+```
+~/famstack-extensions/myapp/
+  stacklet.toml
+  docker-compose.yml
+```
+
+Nothing creates that directory. Make it when you have something to put
+in it, then `stack up myapp`.
+
+Discovery, ids, hooks, CLI plugins, secrets and template variables are
+the same code path in both places, so `stack up myapp` does not care
+which you picked. Being outside the repo means an upgrade cannot take
+your stacklet with it, `git status` never mentions it, and it can be its
+own git repo. Nothing famstack does backs it up, though: it is source
+code, so push it somewhere or include it in your own backup.
+
+`extension_dirs` is a list, so you can keep a dev checkout beside the
+default directory. It is searched in order and the first tree to claim an
+id keeps it, so the repo wins a clash with an extension and an earlier
+directory wins a clash with a later one.
+
+A stacklet here can ship a bot, because the bot runner mounts the first
+extension directory next to the repo one. It mounts only that one, so a
+bot in a later directory is not discovered and `stack up` tells you.
+
+## Saying it isn't finished
+
+```toml
+stage = "incubating"     # or "beta"
+```
+
+`stack list` marks the stacklet and every `stack up` warns that it can
+change or disappear and is not for production. Delete the line (or set
+`"stable"`) when that stops being true.
+
 ## The manifest: stacklet.toml
 
 ```toml
diff --git a/docs/design-notes.md b/docs/design-notes.md
index 72047e3c..960edb26 100644
--- a/docs/design-notes.md
+++ b/docs/design-notes.md
@@ -148,3 +148,24 @@ different from an empty vault.
 
 Both current callers should keep working unchanged through the move. That is
 the test.
+
+## A new compose variable and the .env that predates it (2026-09-20)
+
+Adding `${EXTENSIONS_DIR}:/extensions:ro` to core's compose file exposed
+something older than the mount. `compose_down` and `_refresh_core`'s
+`compose_up` pass no env dict, so Docker resolves `${VAR}` from the `.env`
+sitting beside the compose file. That file is a derived artifact
+([adr-006](adr/adr-006-env-as-derived-artifact.md)), and after an upgrade
+it is one release out of date until something re-renders it.
+
+`stack up <id>` is safe: it renders first and passes the env explicitly, and
+`_refresh_core` calls `refresh_env("core")` before it recreates core. `stack
+down` is not: it never re-renders, so on an instance that has pulled a release
+adding a new variable and has not run any `up` since, the variable resolves
+empty and compose rejects the volume spec. Loud, and fixed by `stack up core`,
+but the user has to know that.
+
+This is not specific to extensions. Every bind mount built from a variable has
+had it since the first one. The fix, if it is worth one, is for the down path
+to re-render env the way the up path does, which is a change to every
+stacklet's teardown and wants its own commit.
diff --git a/docs/stack-reference.md b/docs/stack-reference.md
index 0d4e1f04..fbb3e4f6 100644
--- a/docs/stack-reference.md
+++ b/docs/stack-reference.md
@@ -25,9 +25,34 @@ photos and docs, consumed by the `backup` stacklet).
 
 ## Directory Structure
 
-A stacklet is a directory under `stacklets/` containing at minimum a
-`stacklet.toml` manifest. Everything else is optional — include only what
-you need.
+A stacklet is a directory containing at minimum a `stacklet.toml`
+manifest. Everything else is optional — include only what you need.
+
+Two directories are searched, in this order:
+
+| Location | What belongs there |
+|---|---|
+| `stacklets/` in the repo | The stacklets a release ships and supports. |
+| an extension dir (`[core] extension_dirs`, default `["~/<product>-extensions"]`) | Everything else: a private stacklet, a community one, one still being designed. Outside the repo, so an upgrade cannot take it, and each can be its own git repo. |
+
+`extension_dirs` is a list, searched in the order given. The first tree
+to claim an `id` keeps it, so the repo wins a clash with an extension and
+an earlier extension dir wins a clash with a later one. Nothing creates
+these directories; one that is not there is skipped.
+
+The runtime resolves a stacklet by `id`, never by path, so `stack up <id>`,
+hooks, CLI plugins, secrets and template variables like `{photos_url}`
+behave identically wherever it lives. `stack list` and `stack status`
+group extensions in their own section, and every stacklet in the JSON
+output carries `source` (`repo` or `extension`) and `path`.
+
+One asymmetry: a compose file cannot iterate a list, so the bot runner
+bind-mounts the **first** extension dir only. A stacklet that ships a bot
+belongs there, and `stack up` says so when it is somewhere else. While
+that directory does not exist, the mount gets an empty stand-in under
+`.stack/`, because a bind mount needs a source and an instance without
+extensions should not grow a directory in the admin's home. Any
+`stack up` re-renders core's env, so the real one takes over by itself.
 
 ```
 stacklets/photos/
@@ -96,6 +121,7 @@ port        = 42010
 always_on   = true
 type        = "host"
 requires    = ["core", "messages"]
+stage       = "incubating"
 ```
 
 | Field | Type | Default | Description |
@@ -106,6 +132,7 @@ requires    = ["core", "messages"]
 | `type` | string | `"docker"` | `"docker"` (default) or `"host"`. Host stacklets install native macOS software (brew, compiled binaries) alongside optional Docker containers. |
 | `requires` | list | `[]` | Stacklet IDs that must be enabled before this one. The runtime enforces ordering on `stack up` and prevents destroying dependencies. |
 | `build` | bool | false | If true, the stacklet has a local Dockerfile. `stack up` rebuilds the image on every run instead of pulling from a registry. Use for stacklets with custom code (bots, agents). |
+| `stage` | string | `"stable"` | How finished the stacklet is. `"stable"` is silent. Any other value (`"beta"`, `"incubating"`, or your own) is shown in `stack list` and warned about on every `stack up`. |
 | `required_secrets` | list | `[]` | Secret names (unprefixed, as `ctx.secret()` reads them) the stacklet cannot work without. `stack doctor` reports any that are absent and points at `stack setup <id>`. Declare a secret here when it is minted by `on_install_success`, since that hook never runs again on an instance that is already installed. |
 
 ### Upstream
diff --git a/lib/stack/cli.py b/lib/stack/cli.py
index 1d777b6c..40b9df48 100644
--- a/lib/stack/cli.py
+++ b/lib/stack/cli.py
@@ -612,8 +612,9 @@ def print_up_success(result: dict, stck: Stack) -> None:
     print(f"  {'Your data':<14}  {DIM}{display}{RESET}")
     print()
 
-    for w_msg in result.get("warnings", []):
-        print(f"  {ORANGE}\u26a0{RESET}  {w_msg}")
+    # Warnings are streamed by the output adapter as they happen, which
+    # is before the containers start and also covers `up all`, where no
+    # banner is printed. The result still carries them for API callers.
 
     # Next steps — rendered from manifest hints with credentials
     hints = result.get("hints", [])
@@ -627,6 +628,36 @@ def print_up_success(result: dict, stck: Stack) -> None:
     print()
 
 
+def _short_path(path) -> str:
+    """Home-relative path for display."""
+    home = str(Path.home())
+    text = str(path)
+    return text.replace(home, "~", 1) if text.startswith(home) else text
+
+
+def _split_by_origin(stacklets: list[dict]) -> tuple[list[dict], list[dict]]:
+    """Stacklets the release ships, then the ones loaded from elsewhere.
+
+    Two lists rather than one, because where a stacklet came from decides
+    who supports it. Mixing them into a single column asks the reader to
+    remember which of eleven names is not ours.
+    """
+    shipped = [s for s in stacklets if s.get("source") != "extension"]
+    extensions = [s for s in stacklets if s.get("source") == "extension"]
+    return shipped, extensions
+
+
+def print_extensions_section(extensions: list[dict], dirs: list) -> None:
+    """The extensions half of `list` and `status`. Silent when empty."""
+    from .prompt import status_list
+    if not extensions:
+        return
+    where = ", ".join(_short_path(d) for d in dirs)
+    print(f"  {BOLD}Extensions{RESET}  {DIM}{where}{RESET}" if where
+          else f"  {BOLD}Extensions{RESET}")
+    status_list(extensions)
+
+
 def print_list(result: dict, stck=None) -> None:
     """Stacklet list with status colors."""
     from .prompt import DIM, RESET, status_list
@@ -634,7 +665,9 @@ def print_list(result: dict, stck=None) -> None:
     if not stacklets:
         print("\n  No stacklets found.\n")
         return
-    status_list(stacklets)
+    shipped, extensions = _split_by_origin(stacklets)
+    status_list(shipped)
+    print_extensions_section(extensions, result.get("extension_dirs", []))
     sha = stck._git_commit() if stck else ""
     version_info = f"  {DIM}{VERSION} ({sha}){RESET}" if sha else ""
     print(f"  {result.get('online', 0)}/{result.get('total', 0)} online{version_info}")
@@ -684,8 +717,10 @@ def print_status(result: dict) -> None:
     # Stacklet list
     stacklets = result.get("stacklets", [])
     if stacklets:
+        shipped, extensions = _split_by_origin(stacklets)
         print(f"  {BOLD}Stacklets{RESET}")
-        status_list(stacklets)
+        status_list(shipped)
+        print_extensions_section(extensions, result.get("extension_dirs", []))
         online = result.get("online", 0)
         total = result.get("total", 0)
         print(f"  {online}/{total} online")
@@ -1203,6 +1238,13 @@ def handle_uninstall(stck, args):
         display = str(stck.data).replace(home, "~", 1)
         print(f"\n  {RED}Data directory: {display}{RESET}")
         print(f"  {RED}This contains all your photos, messages, documents, etc.{RESET}")
+        # Extension stacklets are source code, not data, and they live in
+        # the data dir by default. Say so before the wipe, not after.
+        doomed = [d for d in stck.extension_dirs
+                  if d.exists() and d.is_relative_to(stck.data)]
+        for d in doomed:
+            print(f"  {RED}It also contains your extension stacklets "
+                  f"({_short_path(d)}).{RESET}")
         print(f"  {RED}This action is irreversible.{RESET}\n")
         try:
             rm_data = input("  Type 'delete' to remove all data: ").strip()
diff --git a/lib/stack/prompt.py b/lib/stack/prompt.py
index bf262e96..3b7e9e49 100644
--- a/lib/stack/prompt.py
+++ b/lib/stack/prompt.py
@@ -95,6 +95,19 @@ def bullet(text):
 
 # ── Status list ───────────────────────────────────────────────────────────────
 
+def stage_badge(s):
+    """Trailing marker for a stacklet line: the stage it claims.
+
+    A stable stacklet carries none, so a normal list reads exactly as it
+    did. Anything else is the stacklet saying it is unfinished, which an
+    operator needs before reading anything into its state.
+    """
+    stage = s.get("stage", "stable")
+    if not stage or stage == "stable":
+        return ""
+    return f"  {ORANGE}{stage}{RESET}"
+
+
 def status_list(stacklets):
     """Render a compact stacklet status table.
 
@@ -117,22 +130,23 @@ def status_list(stacklets):
         visible_len = len(name) + len(f" ({sid})") if sid and sid != name else len(name)
         col = 28
         pad = max(1, col - visible_len)
+        badges = stage_badge(s)
         if s.get("degraded"):
-            out(f"  {ORANGE}\u26a0{RESET} {label}{' ' * pad} {ORANGE}degraded{RESET}")
+            out(f"  {ORANGE}\u26a0{RESET} {label}{' ' * pad} {ORANGE}degraded{RESET}{badges}")
             for issue in s.get("health_issues", []):
                 out(f"      {ORANGE}{issue}{RESET}")
         elif s.get("online"):
             port = s.get("port")
             url = f"  {DIM}localhost:{port}{RESET}" if port else ""
-            out(f"  {GREEN}\u2713{RESET} {label}{' ' * pad} {GREEN}online{RESET}{url}")
+            out(f"  {GREEN}\u2713{RESET} {label}{' ' * pad} {GREEN}online{RESET}{url}{badges}")
         elif s.get("starting"):
-            out(f"  {TEAL}\u25cb{RESET} {label}{' ' * pad} {TEAL}starting{RESET}")
+            out(f"  {TEAL}\u25cb{RESET} {label}{' ' * pad} {TEAL}starting{RESET}{badges}")
         elif s.get("failing"):
-            out(f"  {RED}\u2717{RESET} {label}{' ' * pad} {RED}failing{RESET}")
+            out(f"  {RED}\u2717{RESET} {label}{' ' * pad} {RED}failing{RESET}{badges}")
         elif s.get("enabled"):
-            out(f"  {ORANGE}\u25cb{RESET} {label}{' ' * pad} {ORANGE}stopped{RESET}")
+            out(f"  {ORANGE}\u25cb{RESET} {label}{' ' * pad} {ORANGE}stopped{RESET}{badges}")
         else:
-            out(f"  {DIM}\u2022{RESET} {label}{' ' * pad} {DIM}available{RESET}")
+            out(f"  {DIM}\u2022{RESET} {label}{' ' * pad} {DIM}available{RESET}{badges}")
     nl()
 
 
diff --git a/lib/stack/stack.py b/lib/stack/stack.py
index f4811b81..7ade9f3c 100644
--- a/lib/stack/stack.py
+++ b/lib/stack/stack.py
@@ -60,6 +60,43 @@ def _mail_accounts_env(mail_cfg: dict, secret_lookup) -> str:
     return json.dumps(accounts) if accounts else ""
 
 
+# ── Stages ────────────────────────────────────────────────────────────────
+
+STABLE = "stable"
+
+_STAGE_WARNINGS = {
+    "incubating": (
+        "{name} is incubating: experimental, it can change or disappear in "
+        "any release, and its data may not survive an upgrade. "
+        "Not for production."
+    ),
+    "beta": (
+        "{name} is beta: it works, but config and data layout can still "
+        "change between releases. Back up before you upgrade. "
+        "Not for production."
+    ),
+}
+
+_UNKNOWN_STAGE_WARNING = (
+    "{name} is marked '{stage}': it is not a finished stacklet and can "
+    "change or disappear in any release. Not for production."
+)
+
+
+def stage_warning(stage: str, name: str) -> str:
+    """What to tell someone starting a stacklet at this stage.
+
+    Empty for a stable stacklet, which is the default and the silent
+    case. Every other value is a claim of unfinishedness, so an
+    unrecognised one warns too: the runtime repeats what the manifest
+    says instead of policing a list of allowed words.
+    """
+    if not stage or stage == STABLE:
+        return ""
+    template = _STAGE_WARNINGS.get(stage, _UNKNOWN_STAGE_WARNING)
+    return template.format(name=name, stage=stage)
+
+
 class StackletNotHealthyError(RuntimeError):
     """wait_for_healthy timed out waiting for the declared [health] probe."""
 
@@ -144,39 +181,125 @@ def _set_cfg(self, section: str, key: str, value: str):
 
     # ── Discovery ─────────────────────────────────────────────────────
 
+    @property
+    def extension_dirs(self) -> list[Path]:
+        """Every directory searched for stacklets the repo does not ship.
+
+        The repo carries the stacklets a release supports. Anything else
+        lives here: a stacklet written for one household, a community
+        one, one still being designed. Keeping them out of the repo means
+        no ignore rules and no long-lived branch to rebase.
+
+        `[core] extension_dirs` takes a list, searched in the order given
+        (a bare string is read as a one-entry list). The default is a
+        single directory in the admin's home, named after the product:
+        `~/famstack-extensions`. It is deliberately outside both the repo
+        and the data dir. The repo is replaced on upgrade and would take
+        the admin's code with it; the data dir is what running services
+        write, not where source belongs.
+
+        Nothing creates it. An instance with no extensions simply has no
+        such directory, and discovery skips what is not there.
+        """
+        configured = self.config.get("core", {}).get("extension_dirs")
+        if isinstance(configured, str):
+            configured = [configured]
+        if not configured:
+            return [Path.home() / f"{self.product_name()}-extensions"]
+        return [Path(d).expanduser() for d in configured]
+
+    @property
+    def mounted_extension_dir(self) -> Path:
+        """The extension dir containers see, which is the first one.
+
+        A compose file cannot iterate a list, so exactly one directory is
+        bind-mounted into the bot runner. It is also where a new
+        extension belongs unless the admin says otherwise.
+        """
+        return self.extension_dirs[0]
+
+    @property
+    def extension_mount_source(self) -> Path:
+        """The host path the bot runner bind-mounts at /extensions.
+
+        The mounted extension dir, once it exists. A bind mount needs its
+        source to exist, and an instance with no extensions should not
+        grow a directory in someone's home it never asked for, so until
+        then the mount gets an empty stand-in in the runtime state dir.
+
+        Rendering is pure; core's on_start creates whichever path this
+        returns. The switch costs nothing to miss: any `stack up` re-
+        renders core's env, so the real directory takes over as soon as
+        there is one.
+        """
+        mounted = self.mounted_extension_dir
+        if mounted.is_dir():
+            return mounted
+        return self.instance_dir / ".stack" / "no-extensions"
+
     def discover(self) -> list[dict]:
-        """Find all stacklets under root/stacklets/.
+        """Find every stacklet, in the repo and in the extensions dir.
 
         Walks the filesystem — no registry needed. A directory with a
-        stacklet.toml is a stacklet.
+        stacklet.toml is a stacklet, wherever it sits.
+
+        The repo is searched first, then each extension dir in the order
+        configured. The first tree to claim an id keeps it: an extension
+        can add a stacklet, never replace one the release ships, and two
+        extension dirs resolve the way a PATH does. The loser is reported
+        at debug level, because discovery runs on every command and a
+        permanent warning would be noise.
         """
-        stacklets_dir = self.root / "stacklets"
-        if not stacklets_dir.exists():
-            return []
+        roots = [(self.root / "stacklets", "repo")]
+        roots += [(d, "extension") for d in self.extension_dirs]
 
         result = []
-        for manifest_path in sorted(stacklets_dir.glob("*/stacklet.toml")):
-            try:
-                with open(manifest_path, "rb") as f:
-                    raw = tomllib.load(f)
-            except (tomllib.TOMLDecodeError, OSError):
+        seen = set()
+        for root, source in roots:
+            if not root.is_dir():
                 continue
-
-            sid = raw.get("id", manifest_path.parent.name)
-            result.append({
-                "id":          sid,
-                "name":        raw.get("name", sid),
-                "description": raw.get("description", ""),
-                "version":     raw.get("version", ""),
-                "port":        raw.get("port"),
-                "category":    raw.get("category", ""),
-                "always_on":   raw.get("always_on", False),
-                "enabled":     self._is_set_up(sid),
-                "path":        str(manifest_path.parent),
-                "manifest":    raw,
-            })
+            for manifest_path in sorted(root.glob("*/stacklet.toml")):
+                entry = self._read_manifest(manifest_path, source)
+                if entry is None:
+                    continue
+                if entry["id"] in seen:
+                    self.output.debug(
+                        f"Ignoring {source} stacklet {manifest_path.parent}: "
+                        f"id '{entry['id']}' is already taken")
+                    continue
+                seen.add(entry["id"])
+                result.append(entry)
         return result
 
+    def _read_manifest(self, manifest_path: Path, source: str) -> dict | None:
+        """One stacklet.toml as the dict the rest of the runtime speaks.
+
+        Returns None for a manifest that cannot be read or parsed: a
+        broken stacklet drops out of the list instead of breaking every
+        command that lists stacklets.
+        """
+        try:
+            with open(manifest_path, "rb") as f:
+                raw = tomllib.load(f)
+        except (tomllib.TOMLDecodeError, OSError):
+            return None
+
+        sid = raw.get("id", manifest_path.parent.name)
+        return {
+            "id":          sid,
+            "name":        raw.get("name", sid),
+            "description": raw.get("description", ""),
+            "version":     raw.get("version", ""),
+            "port":        raw.get("port"),
+            "category":    raw.get("category", ""),
+            "always_on":   raw.get("always_on", False),
+            "stage":       raw.get("stage", STABLE),
+            "source":      source,
+            "enabled":     self._is_set_up(sid),
+            "path":        str(manifest_path.parent),
+            "manifest":    raw,
+        }
+
     def _find_stacklet(self, stacklet_id: str) -> dict | None:
         """Find a stacklet by ID. Returns the stacklet dict or None."""
         for s in self.discover():
@@ -205,6 +328,7 @@ def _build_template_vars(self) -> dict:
         template_vars = {
             # Core config
             "data_dir":              str(self.data),
+            "extension_mount":       str(self.extension_mount_source),
             "domain":                self._cfg("core", "domain"),
             "language":              self._cfg("core", "language", self._cfg("ai", "language", "en")),
             "timezone":              self._cfg("core", "timezone", "UTC"),
@@ -478,6 +602,10 @@ def list(self) -> dict:
             "total": len(stacklets),
             "enabled": len(set_up),
             "online": len(online),
+            # Every entry carries its own `source` and `path`; these are
+            # the directories the extension ones were loaded from, for a
+            # caller that wants to name them without deriving them.
+            "extension_dirs": [str(d) for d in self.extension_dirs],
         }
 
     def status(self) -> dict:
@@ -786,6 +914,31 @@ def up(self, stacklet_id: str) -> dict:
         first_run = self._is_first_run(stacklet_id)
         stacklet_dir = Path(s["path"])
 
+        # ── What to say before anything starts ────────────────────
+        # Whoever runs this should know what they are getting before the
+        # containers are up, not after.
+        name = s.get("name", stacklet_id)
+        stage = s.get("stage", STABLE)
+        warnings = []
+        warning = stage_warning(stage, name)
+        if warning:
+            self.output.warn(warning)
+            warnings.append(warning)
+
+        # Only one extension dir is mounted into the bot runner, because a
+        # compose file cannot iterate a list. A bot in any other one is
+        # never discovered, and nothing else would ever say so.
+        if (s.get("source") == "extension"
+                and (stacklet_dir / "bot").is_dir()
+                and stacklet_dir.parent != self.mounted_extension_dir):
+            unmounted = (
+                f"{name} ships a bot, but the bot runner only mounts "
+                f"{self.mounted_extension_dir}. Move the stacklet there, or "
+                f"put that directory first in [core] extension_dirs."
+            )
+            self.output.warn(unmounted)
+            warnings.append(unmounted)
+
         # ── Check dependencies ────────────────────────────────────
         for dep in manifest.get("requires", []):
             if not self._is_set_up(dep):
@@ -871,6 +1024,10 @@ def _step(msg):
             "description": s.get("description", ""),
             "port": s.get("port"),
             "hints": hints,
+            "stage": stage,
+            "source": s.get("source", "repo"),
+            "path": s["path"],
+            "warnings": warnings,
         }
 
     def run_on_install_success(self, stacklet_id: str, step_fn=None) -> bool:
diff --git a/stack.example.toml b/stack.example.toml
index 43e5cf2a..26365deb 100644
--- a/stack.example.toml
+++ b/stack.example.toml
@@ -21,6 +21,25 @@ domain = ""
 # The ~ shorthand is expanded by the stack CLI.
 data_dir = "~/famstack-data"
 
+# Where stacklets that don't ship with famstack live: one you wrote, one
+# you cloned, one that isn't finished yet. Any subdirectory with a
+# stacklet.toml is discovered exactly like the built-in ones, so
+# `stack up <id>` works the same.
+#
+# Defaults to ~/famstack-extensions, which nothing creates: make it when
+# you have a stacklet to put in it. Deliberately outside both this repo
+# (an upgrade replaces it) and the data dir (that is what running services
+# write, not where source belongs).
+#
+# A list if you want more than one, searched in order, so the first entry
+# wins a name clash. It is also the one mounted into the bot runner, so a
+# stacklet that ships a bot belongs there.
+#
+# Spelled out rather than left to the default, so the path is greppable
+# and does not move if you rename the stack. Add a second entry for a
+# working copy: ["~/famstack-extensions", "~/dev/my-stacklets"].
+extension_dirs = ["~/famstack-extensions"]
+
 # Timezone for containers that need one (Immich, Paperless, cron jobs, etc.)
 # Full list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 timezone = "UTC"
diff --git a/stacklets/core/bot-runner/main.py b/stacklets/core/bot-runner/main.py
index b84c3204..402fff63 100644
--- a/stacklets/core/bot-runner/main.py
+++ b/stacklets/core/bot-runner/main.py
@@ -1,7 +1,8 @@
 """Bot runner — discovers and runs bots from across all enabled stacklets.
 
 Convention-based discovery:
-  1. Scans /stacklets/*/bot/bot.toml for enabled stacklets
+  1. Scans /stacklets/*/bot/bot.toml (and /extensions/*, for stacklets
+     that live outside the repo) for enabled stacklets
   2. Waits for Matrix to be available
   3. Creates Matrix accounts and rooms
   4. Launches all bots concurrently in one async process
@@ -39,6 +40,11 @@
 MATRIX_SERVER_NAME = os.environ.get("MATRIX_SERVER_NAME", "")
 DATA_DIR = Path("/data")
 STACKLETS_DIR = Path("/stacklets")
+# Stacklets that do not ship with the repo are mounted from the framework's
+# extensions dir. Both trees have the same shape, so the runner searches
+# them in the order the CLI discovers them: repo first, extensions second.
+EXTENSIONS_DIR = Path("/extensions")
+STACKLET_ROOTS = (STACKLETS_DIR, EXTENSIONS_DIR)
 SETUP_STATE_DIR = Path("/setup-state")
 
 
@@ -93,7 +99,7 @@ def discover_bots():
     bots = []
 
     for stacklet_id in sorted(enabled):
-        bot_dir = STACKLETS_DIR / stacklet_id / "bot"
+        bot_dir = bot_dir_for(stacklet_id)
         for bot_toml in _bot_toml_files(bot_dir):
             logger.info("Found bot declaration: {}", bot_toml)
 
@@ -158,6 +164,20 @@ def discover_bots():
     return bots
 
 
+def bot_dir_for(stacklet_id, roots=STACKLET_ROOTS):
+    """Where a stacklet's bot/ dir is mounted.
+
+    The repo tree wins, matching the CLI: an extension can add a stacklet,
+    never replace one the release ships. Falls back to the repo path when
+    neither exists, so a missing bot logs a path an operator recognises.
+    """
+    for root in roots:
+        candidate = root / stacklet_id / "bot"
+        if candidate.is_dir():
+            return candidate
+    return STACKLETS_DIR / stacklet_id / "bot"
+
+
 def _bot_toml_files(bot_dir):
     """Every bot declaration in a stacklet's bot/ dir.
 
diff --git a/stacklets/core/docker-compose.yml b/stacklets/core/docker-compose.yml
index 959e3565..b971f61d 100644
--- a/stacklets/core/docker-compose.yml
+++ b/stacklets/core/docker-compose.yml
@@ -39,6 +39,10 @@ services:
     volumes:
       # Bot discovery — scans enabled stacklets for bot/ dirs
       - ../../stacklets:/stacklets:ro
+      # The same, for stacklets that live outside the repo. The host path
+      # comes from the framework, so a bot in an extension stacklet is
+      # discovered exactly like one the release ships.
+      - ${EXTENSIONS_DIR}:/extensions:ro
       # Setup state — knows which stacklets are enabled, holds secrets
       - ../../.stack:/setup-state:ro
       # Shared library — resolve_model, compat shims
diff --git a/stacklets/core/hooks/on_start.py b/stacklets/core/hooks/on_start.py
index 893f7586..eaff855e 100644
--- a/stacklets/core/hooks/on_start.py
+++ b/stacklets/core/hooks/on_start.py
@@ -13,6 +13,13 @@
 
 
 def run(ctx):
+    # The bot runner bind-mounts the extension tree, so the source has to
+    # exist before compose starts. Created here rather than left to the
+    # Docker daemon, which would make it root-owned on some runtimes. On
+    # an instance with no extensions this is the empty stand-in, not a
+    # directory in the admin's home.
+    ctx.stack.extension_mount_source.mkdir(parents=True, exist_ok=True)
+
     repo_root = Path(ctx.stack.root)
     api_script = repo_root / "stacklets" / "core" / "famstack-api.py"
     log_dir = Path(ctx.stack.data) / "core" / "logs"
diff --git a/stacklets/core/stacklet.toml b/stacklets/core/stacklet.toml
index f51bd340..433fbc6e 100644
--- a/stacklets/core/stacklet.toml
+++ b/stacklets/core/stacklet.toml
@@ -30,6 +30,12 @@ WATCHTOWER_SCHEDULE = "0 0 3 * * *"
 # Data dir — bot runner mounts this for per-stacklet bot data
 DATA_DIR = "{data_dir}"
 
+# Extension stacklets — the second tree the bot runner scans, so a bot
+# shipped by a stacklet outside the repo runs like any other. Renders the
+# first entry in [core] extension_dirs, or an empty stand-in while that
+# directory does not exist.
+EXTENSIONS_DIR = "{extension_mount}"
+
 # Matrix — bot runner connects to Synapse for all bots
 MATRIX_HOMESERVER  = "http://stack-messages-synapse:8008"
 MATRIX_SERVER_NAME = "{messages_server_name}"
diff --git a/tests/framework/conftest.py b/tests/framework/conftest.py
index aee3e4f3..ebf59bed 100644
--- a/tests/framework/conftest.py
+++ b/tests/framework/conftest.py
@@ -34,12 +34,13 @@ def make_stack(tmp_path):
     from stack import Stack
     from stack.output import CollectorOutput
 
-    def _factory(stacklets=None, config_extra="", output=None):
+    def _factory(stacklets=None, extensions=None, config_extra="", output=None):
         # Write test config
         (tmp_path / "stack.toml").write_text(f"""
 [core]
 domain = ""
 data_dir = "{tmp_path / 'data'}"
+extension_dirs = ["{tmp_path / 'extensions'}"]
 timezone = "Europe/Berlin"
 
 [ai]
@@ -76,6 +77,13 @@ def _factory(stacklets=None, config_extra="", output=None):
             if src.exists():
                 shutil.copytree(src, stacklets_dir / name)
 
+        # Copy fixture stacklets into the extensions dir — the second search
+        # path, for stacklets the release does not ship.
+        for name in (extensions or []):
+            src = FIXTURES_DIR / name
+            if src.exists():
+                shutil.copytree(src, tmp_path / "extensions" / name)
+
         out = output or CollectorOutput()
         return Stack(root=tmp_path, data=tmp_path / "data", output=out)
 
diff --git a/tests/framework/fixtures/guest/docker-compose.yml b/tests/framework/fixtures/guest/docker-compose.yml
new file mode 100644
index 00000000..89d653f3
--- /dev/null
+++ b/tests/framework/fixtures/guest/docker-compose.yml
@@ -0,0 +1,31 @@
+# Minimal container for lifecycle testing, mirroring the `test` fixture
+# on its own port so both can run side by side.
+
+name: stack-guest
+
+services:
+  stack-guest:
+    container_name: stack-guest
+    image: alpine:latest
+    command: >
+      sh -c "while true; do
+        echo -e 'HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nok' |
+        nc -l -p 8080;
+      done"
+    labels:
+      - "com.centurylinklabs.watchtower.enable=false"
+    networks:
+      - stack
+    ports:
+      - "${PORT_BIND_IP:-127.0.0.1}:42098:8080"
+    volumes:
+      - ${GUEST_DATA_DIR}:/data
+    environment:
+      TZ: ${TZ}
+      GUEST_SECRET: ${GUEST_SECRET}
+      GUEST_ADMIN: ${GUEST_ADMIN}
+    restart: unless-stopped
+
+networks:
+  stack:
+    external: true
diff --git a/tests/framework/fixtures/guest/hooks/on_install.py b/tests/framework/fixtures/guest/hooks/on_install.py
new file mode 100644
index 00000000..1c198c42
--- /dev/null
+++ b/tests/framework/fixtures/guest/hooks/on_install.py
@@ -0,0 +1,14 @@
+"""Guest stacklet on_install — proves first-run hooks run outside the repo."""
+
+
+def run(ctx):
+    from pathlib import Path
+
+    data_dir = ctx.env.get("GUEST_DATA_DIR", "")
+    if not data_dir:
+        ctx.step("ERROR: GUEST_DATA_DIR not set")
+        return
+
+    Path(data_dir).mkdir(parents=True, exist_ok=True)
+    (Path(data_dir) / ".install-marker").write_text("installed")
+    ctx.step("on_install complete")
diff --git a/tests/framework/fixtures/guest/stacklet.toml b/tests/framework/fixtures/guest/stacklet.toml
new file mode 100644
index 00000000..538bb9a9
--- /dev/null
+++ b/tests/framework/fixtures/guest/stacklet.toml
@@ -0,0 +1,27 @@
+# stacklet.toml — guest stacklet
+#
+# The same shape as the `test` fixture, but installed into the instance's
+# extensions dir instead of stacklets/: a stacklet the release does not
+# ship. It carries a stage so the lifecycle lane sees the warning path
+# too, which is the realistic pairing — a stacklet usually lives outside
+# the repo because it is not finished.
+
+id          = "guest"
+name        = "Guest"
+description = "Extension stacklet for lifecycle testing (Alpine)"
+version     = "0.1.0"
+category    = "test"
+stage       = "incubating"
+port        = 42098
+
+[env]
+generate = ["GUEST_SECRET"]
+
+[env.defaults]
+GUEST_DATA_DIR = "{data_dir}/guest"
+TZ             = "{timezone}"
+GUEST_ADMIN    = "{admin_username}"
+
+[health]
+url    = "http://localhost:42098/"
+expect = "200"
diff --git a/tests/framework/fixtures/incubating/stacklet.toml b/tests/framework/fixtures/incubating/stacklet.toml
new file mode 100644
index 00000000..9fe381e7
--- /dev/null
+++ b/tests/framework/fixtures/incubating/stacklet.toml
@@ -0,0 +1,13 @@
+# A stacklet that declares itself not ready for production.
+# Tests: stage warnings on `stack up`, the {extension_mount} template var.
+
+id          = "incubating"
+name        = "Incubating"
+description = "Tests the stage contract"
+version     = "0.1.0"
+category    = "test"
+stage       = "incubating"
+
+[env.defaults]
+EXT_DIR = "{extension_mount}"
+TZ      = "{timezone}"
diff --git a/tests/framework/test_config_to_container.py b/tests/framework/test_config_to_container.py
index ac0ae5b3..24d611ca 100644
--- a/tests/framework/test_config_to_container.py
+++ b/tests/framework/test_config_to_container.py
@@ -136,6 +136,7 @@ def test_stack(tmp_path_factory):
 name = "teststack"
 domain = ""
 data_dir = "{data_dir}"
+extension_dirs = ["{stack_root / "extensions"}"]
 timezone = "Europe/Berlin"
 
 [ai]
@@ -404,3 +405,141 @@ def test_secret_change_reaches_container_on_restart(self, isolated_stack):
         env_after = docker_env("stack-test")
         assert env_after.get("TEST_SECRET") == "changed-value-123", \
             f"Expected 'changed-value-123' after restart, got: {env_after.get('TEST_SECRET')}"
+
+
+# ── Stacklets outside the repo ───────────────────────────────────────────
+
+@pytest.fixture(scope="module")
+def guest_stacklet(test_stack):
+    """A stacklet installed the way a user installs one: outside the repo.
+
+    Copied into the instance's extensions dir rather than `stacklets/`,
+    so everything below runs through the same discovery a private or
+    third-party stacklet gets. Torn down like the module's own stacklet,
+    plus the directory the user would have created by hand.
+    """
+    target = test_stack.root / "extensions" / "guest"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(FIXTURES_DIR / "guest", target)
+
+    yield target
+
+    test_stack.run("destroy", "guest", "--yes")
+    subprocess.run(["docker", "rm", "-f", "stack-guest"],
+                   capture_output=True, timeout=10)
+    shutil.rmtree(target.parent, ignore_errors=True)
+
+
+class TestExtensionStackletLifecycle:
+    """A stacklet in the extensions dir gets the whole lifecycle.
+
+    These assertions are deliberately about internal state rather than
+    output: which tree the runtime resolved the stacklet from, where the
+    derived `.env` landed, where the secret and the setup marker went,
+    what reached the container, and what `destroy` takes with it. A
+    stacklet outside the repo that only *looks* installed is the failure
+    this class exists to catch.
+    """
+
+    def test_up_starts_a_container_from_the_extensions_dir(self, test_stack, guest_stacklet):
+        test_stack.run_ok("up", "guest")
+
+        assert container_running("stack-guest")
+        assert not (test_stack.root / "stacklets" / "guest").exists(), \
+            "the stacklet ran without ever being in the repo"
+
+    def test_env_is_derived_next_to_the_compose_file_it_feeds(self, test_stack, guest_stacklet):
+        """`.env` is a derived artifact, written beside the compose file
+        that reads it. For an extension that is the user's directory, not
+        anything in the repo."""
+        test_stack.run_ok("up", "guest")
+
+        rendered = {}
+        for line in (guest_stacklet / ".env").read_text().splitlines():
+            if "=" in line:
+                key, value = line.split("=", 1)
+                rendered[key] = value.strip('"')
+        assert rendered["GUEST_DATA_DIR"] == str(test_stack.data / "guest")
+        assert rendered["TZ"] == "Europe/Berlin"
+
+    def test_first_run_state_is_keyed_by_id_not_location(self, test_stack, guest_stacklet):
+        """Hooks, secrets and the setup marker all resolve by id, so an
+        extension is installed in exactly the same places as a shipped
+        stacklet: data under the data dir, state under .stack/."""
+        test_stack.run_ok("up", "guest")
+
+        assert (test_stack.data / "guest" / ".install-marker").read_text() == "installed"
+        assert (test_stack.root / ".stack" / "guest.setup-done").exists()
+        assert "guest__GUEST_SECRET" in (
+            test_stack.root / ".stack" / "secrets.toml").read_text()
+
+    def test_the_rendered_env_reaches_the_container(self, test_stack, guest_stacklet):
+        """The whole pipeline, for a stacklet the release never saw:
+        stack.toml and users.toml to template vars to .env to compose."""
+        test_stack.run_ok("up", "guest")
+
+        env = docker_env("stack-guest")
+        assert env.get("TZ") == "Europe/Berlin"
+        assert env.get("GUEST_ADMIN") == "stackadmin"
+        assert env.get("GUEST_SECRET"), "generated secret should reach the container"
+
+    def test_list_reports_where_it_came_from(self, test_stack, guest_stacklet):
+        test_stack.run_ok("up", "guest")
+
+        listing = test_stack.run("list", "--json")
+        guest = next(s for s in listing["stacklets"] if s["id"] == "guest")
+        assert guest["source"] == "extension"
+        assert guest["stage"] == "incubating"
+        assert Path(guest["path"]) == guest_stacklet
+        assert guest["online"] is True
+        assert listing["extension_dirs"] == [str(test_stack.root / "extensions")]
+
+    def test_every_up_repeats_the_stage_warning(self, test_stack, guest_stacklet):
+        """Not a first-run notice. Whoever runs it, whenever, is told."""
+        test_stack.run_ok("up", "guest")
+        stdout, stderr = test_stack.run_pretty_ok("up", "guest")
+
+        combined = stdout + stderr
+        assert "incubating" in combined
+        assert "Not for production" in combined
+
+    def test_the_repo_wins_a_name_clash(self, test_stack, guest_stacklet):
+        """An extension cannot shadow a stacklet the instance ships, and
+        the proof is the path the runtime resolved, not the name."""
+        impostor = test_stack.root / "extensions" / "test"
+        shutil.copytree(FIXTURES_DIR / "test", impostor)
+        try:
+            listing = test_stack.run("list", "--json")
+            entries = [s for s in listing["stacklets"] if s["id"] == "test"]
+
+            assert len(entries) == 1
+            assert entries[0]["source"] == "repo"
+            assert Path(entries[0]["path"]) == test_stack.root / "stacklets" / "test"
+        finally:
+            shutil.rmtree(impostor)
+
+    def test_down_keeps_everything_but_the_container(self, test_stack, guest_stacklet):
+        test_stack.run_ok("up", "guest")
+        test_stack.run_ok("down", "guest")
+
+        assert wait_for_stop("stack-guest"), "Container did not stop in time"
+        assert (test_stack.data / "guest").exists()
+        assert (test_stack.root / ".stack" / "guest.setup-done").exists()
+
+    def test_destroy_removes_the_state_and_leaves_the_stacklet(self, test_stack, guest_stacklet):
+        """The source is the user's, not ours. Destroy clears what the
+        runtime created and leaves the stacklet where they put it, so it
+        goes back to available rather than disappearing."""
+        test_stack.run_ok("up", "guest")
+        test_stack.run_ok("destroy", "guest", "--yes")
+
+        assert wait_for_stop("stack-guest"), "Container did not stop in time"
+        assert not (test_stack.data / "guest").exists()
+        assert not (test_stack.root / ".stack" / "guest.setup-done").exists()
+        assert "guest__GUEST_SECRET" not in (
+            test_stack.root / ".stack" / "secrets.toml").read_text()
+
+        assert (guest_stacklet / "stacklet.toml").exists()
+        listing = test_stack.run("list", "--json")
+        guest = next(s for s in listing["stacklets"] if s["id"] == "guest")
+        assert guest["enabled"] is False
diff --git a/tests/framework/test_extensions.py b/tests/framework/test_extensions.py
new file mode 100644
index 00000000..1941748e
--- /dev/null
+++ b/tests/framework/test_extensions.py
@@ -0,0 +1,330 @@
+"""Extension stacklets and the stage contract.
+
+The repo ships the stacklets a release supports. Everything else — a
+stacklet written for one household, a community one, one still being
+designed — lives in the extensions directory and is discovered from
+there. A stacklet author gets the same manifest, the same id, the same
+lifecycle either way; only the location differs.
+
+`stage` is the other half: a stacklet says how finished it is, and the
+runtime repeats that to whoever runs it.
+"""
+
+import shutil
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+CORE = REPO_ROOT / "stacklets" / "core"
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+
+
+def _stacklet_at(root: Path, sid: str, name: str) -> Path:
+    """Write a minimal stacklet into `root` and return `root`."""
+    (root / sid).mkdir(parents=True, exist_ok=True)
+    (root / sid / "stacklet.toml").write_text(f'id = "{sid}"\nname = "{name}"\n')
+    return root
+
+
+def _unconfigure(stck, key: str) -> None:
+    """Drop a [core] key so the framework's own default applies."""
+    cfg = stck.instance_dir / "stack.toml"
+    cfg.write_text("\n".join(
+        line for line in cfg.read_text().splitlines()
+        if not line.startswith(key)))
+
+
+def _configure(stck, line: str) -> None:
+    """Set a [core] key in the instance's stack.toml, replacing any the
+    test fixture already wrote (a duplicate key is a TOML error)."""
+    _unconfigure(stck, line.split("=", 1)[0].strip())
+    cfg = stck.instance_dir / "stack.toml"
+    cfg.write_text(cfg.read_text().replace("[core]", f"[core]\n{line}", 1))
+
+
+def _runner():
+    """The bot runner module, imported the way the container sees it."""
+    sys.path.insert(0, str(CORE / "bot-runner"))
+    import main
+
+    return main
+
+
+class TestExtensionDiscovery:
+    """Stacklets outside the repo are first-class."""
+
+    def test_finds_stacklets_in_the_extensions_dir(self, make_stack):
+        stck = make_stack(stacklets=["basic"], extensions=["with_hooks"])
+        ids = {s["id"] for s in stck.discover()}
+        assert ids == {"basic", "with_hooks"}
+
+    def test_reports_where_a_stacklet_came_from(self, make_stack):
+        """`source` is what tells an operator which tree to edit."""
+        stck = make_stack(stacklets=["basic"], extensions=["with_hooks"])
+        by_id = {s["id"]: s for s in stck.discover()}
+        assert by_id["basic"]["source"] == "repo"
+        assert by_id["with_hooks"]["source"] == "extension"
+
+    def test_path_points_into_the_extensions_dir(self, make_stack):
+        """Hooks, compose files and CLI plugins all resolve from `path`."""
+        stck = make_stack(extensions=["with_hooks"])
+        found = stck.discover()[0]
+        assert Path(found["path"]) == stck.mounted_extension_dir / "with_hooks"
+
+    def test_repo_wins_a_name_clash(self, make_stack):
+        """An extension must never shadow a stacklet the release ships."""
+        stck = make_stack(stacklets=["basic"])
+        clash = stck.mounted_extension_dir / "basic"
+        clash.mkdir(parents=True)
+        (clash / "stacklet.toml").write_text(
+            'id = "basic"\nname = "Impostor"\n')
+
+        found = [s for s in stck.discover() if s["id"] == "basic"]
+        assert len(found) == 1
+        assert found[0]["name"] == "Basic"
+        assert found[0]["source"] == "repo"
+
+    def test_a_configured_dir_that_is_not_there_is_skipped(self, make_stack):
+        """Most instances never grow one. Its absence is not a failure."""
+        stck = make_stack(stacklets=["basic"])
+
+        assert not stck.mounted_extension_dir.exists()
+        assert [s["id"] for s in stck.discover()] == ["basic"]
+
+    def test_the_default_is_a_product_named_dir_in_the_admins_home(self, make_stack):
+        """Not in the repo, which an upgrade replaces, and not in the data
+        dir, which is what running services write. The admin's own."""
+        stck = make_stack()
+        _unconfigure(stck, "extension_dirs")
+
+        assert stck.extension_dirs == [Path.home() / "stack-extensions"]
+        assert stck.root not in stck.mounted_extension_dir.parents
+        assert stck.data not in stck.mounted_extension_dir.parents
+
+    def test_nothing_creates_the_default(self, make_stack):
+        """An instance with no extensions has no such directory."""
+        stck = make_stack(stacklets=["basic"])
+        _unconfigure(stck, "extension_dirs")
+        before = stck.mounted_extension_dir.exists()
+
+        stck.up("basic")
+
+        assert stck.mounted_extension_dir.exists() == before
+
+    def test_a_single_dir_can_be_written_as_a_string(self, make_stack, tmp_path):
+        """TOML invites `extension_dirs = "~/dev"`. Read it as one entry
+        rather than as a list of characters."""
+        elsewhere = _stacklet_at(tmp_path / "dev", "basic", "From Dev")
+
+        stck = make_stack()
+        _configure(stck, f'extension_dirs = "{elsewhere}"')
+
+        assert stck.extension_dirs == [elsewhere]
+        assert [s["name"] for s in stck.discover()] == ["From Dev"]
+
+    def test_several_dirs_are_searched_in_order(self, make_stack, tmp_path):
+        """A dev checkout beside the default one, resolved like a PATH."""
+        first = _stacklet_at(tmp_path / "dev", "basic", "From Dev")
+        second = _stacklet_at(tmp_path / "vendor", "basic", "From Vendor")
+        _stacklet_at(tmp_path / "vendor", "extra", "Only In Vendor")
+
+        stck = make_stack()
+        _configure(stck, f'extension_dirs = ["{first}", "{second}"]')
+
+        assert stck.extension_dirs == [first, second]
+        by_id = {s["id"]: s for s in stck.discover()}
+        assert by_id["basic"]["name"] == "From Dev", "earlier dir wins the id"
+        assert by_id["extra"]["name"] == "Only In Vendor"
+
+    def test_the_first_dir_is_the_one_containers_see(self, make_stack, tmp_path):
+        """Compose cannot iterate a list, so one dir is bind-mounted, and
+        `{extensions_dir}` names that one wherever the stacklet itself
+        was loaded from."""
+        first = _stacklet_at(tmp_path / "dev", "quiet", "Quiet")
+        second = tmp_path / "vendor"
+        shutil.copytree(FIXTURES_DIR / "incubating", second / "incubating")
+
+        stck = make_stack()
+        _configure(stck, f'extension_dirs = ["{first}", "{second}"]')
+
+        assert stck.mounted_extension_dir == first
+        assert stck.env("incubating")["EXT_DIR"] == str(first)
+
+    def test_a_bot_outside_the_mounted_dir_is_flagged(self, make_stack, tmp_path):
+        """The one thing a second dir silently costs: the bot runner
+        cannot see it. Nothing else in the system would ever say so."""
+        mounted = _stacklet_at(tmp_path / "dev", "quiet", "Quiet")
+        other = _stacklet_at(tmp_path / "vendor", "chatty", "Chatty")
+        (other / "chatty" / "bot").mkdir()
+
+        stck = make_stack()
+        _configure(stck, f'extension_dirs = ["{mounted}", "{other}"]')
+
+        assert stck.up("quiet")["warnings"] == []
+        warning = " ".join(stck.up("chatty")["warnings"])
+        assert "bot runner" in warning
+        assert str(mounted) in warning
+
+    def test_the_mount_source_is_a_template_var(self, make_stack):
+        """core renders EXTENSIONS_DIR from it to mount the tree for bots."""
+        stck = make_stack(extensions=["incubating"])
+        env = stck.env("incubating")
+        assert env["EXT_DIR"] == str(stck.mounted_extension_dir)
+
+    def test_the_mount_falls_back_while_there_is_nothing_to_mount(self, make_stack):
+        """A bind mount needs a source that exists. An instance with no
+        extensions gets an empty stand-in in the runtime state dir rather
+        than a directory in the admin's home it never asked for."""
+        stck = make_stack(stacklets=["incubating"])
+
+        mount = stck.extension_mount_source
+        assert mount == stck.instance_dir / ".stack" / "no-extensions"
+        assert stck.env("incubating")["EXT_DIR"] == str(mount)
+
+    def test_the_real_dir_takes_over_as_soon_as_it_exists(self, make_stack):
+        stck = make_stack(stacklets=["incubating"])
+        stck.mounted_extension_dir.mkdir(parents=True)
+
+        assert stck.extension_mount_source == stck.mounted_extension_dir
+
+
+class TestStage:
+    """A stacklet declares how finished it is; `stack up` repeats it."""
+
+    def test_stage_defaults_to_stable(self, make_stack):
+        stck = make_stack(stacklets=["basic"])
+        assert stck.discover()[0]["stage"] == "stable"
+
+    def test_stage_is_read_from_the_manifest(self, make_stack):
+        stck = make_stack(stacklets=["incubating"])
+        assert stck.discover()[0]["stage"] == "incubating"
+
+    def test_up_warns_about_an_incubating_stacklet(self, make_stack):
+        """The warning is the whole point: no promises, not for production."""
+        stck = make_stack(stacklets=["incubating"])
+        result = stck.up("incubating")
+
+        assert result["stage"] == "incubating"
+        warning = " ".join(result["warnings"])
+        assert "incubating" in warning.lower()
+        assert "production" in warning.lower()
+        assert warning in " ".join(stck.output.warnings)
+
+    def test_up_says_nothing_about_a_stable_stacklet(self, make_stack):
+        stck = make_stack(stacklets=["basic"])
+        result = stck.up("basic")
+        assert result["warnings"] == []
+        assert stck.output.warnings == []
+
+    def test_an_unknown_stage_still_warns(self, make_stack):
+        """Anything but 'stable' is a claim of unfinishedness. Repeat it."""
+        stck = make_stack()
+        ext = stck.mounted_extension_dir / "alpha_thing"
+        ext.mkdir(parents=True)
+        (ext / "stacklet.toml").write_text(
+            'id = "alpha_thing"\nname = "Alpha Thing"\nstage = "alpha"\n')
+
+        result = stck.up("alpha_thing")
+        assert result["source"] == "extension"
+        assert "alpha" in " ".join(result["warnings"]).lower()
+
+
+class TestListRendering:
+    """`stack list` keeps the two origins apart and repeats the stage."""
+
+    def _listing(self):
+        return {
+            "stacklets": [
+                {"id": "photos", "name": "Photos", "source": "repo",
+                 "online": True, "enabled": True},
+                {"id": "drive", "name": "Drive", "source": "extension",
+                 "stage": "incubating"},
+            ],
+            "online": 1,
+            "total": 2,
+            "extension_dirs": ["/data/extensions"],
+        }
+
+    def test_extensions_are_listed_under_their_own_heading(self, capsys):
+        """Where a stacklet came from decides who supports it, so the
+        reader should not have to remember which name is not ours."""
+        from stack.cli import print_list
+
+        print_list(self._listing())
+        out = capsys.readouterr().out
+
+        assert out.index("Photos") < out.index("Extensions") < out.index("Drive")
+
+    def test_the_heading_names_the_directory(self, capsys):
+        """The answer to "where did this come from" is in the output, not
+        in the docs."""
+        from stack.cli import print_list
+
+        print_list(self._listing())
+        assert "/data/extensions" in capsys.readouterr().out
+
+    def test_an_instance_without_extensions_reads_as_before(self, capsys):
+        from stack.cli import print_list
+
+        listing = self._listing()
+        listing["stacklets"] = listing["stacklets"][:1]
+        print_list(listing)
+
+        assert "Extensions" not in capsys.readouterr().out
+
+    def test_the_stage_is_marked_on_the_stacklet_line(self, capsys):
+        from stack.prompt import status_list
+
+        status_list([{"id": "drive", "name": "Drive", "stage": "incubating"}])
+        assert "incubating" in capsys.readouterr().out
+
+    def test_a_stable_stacklet_line_is_unchanged(self, capsys):
+        from stack.prompt import status_list
+
+        status_list([{"id": "photos", "name": "Photos", "stage": "stable",
+                      "online": True, "enabled": True}])
+        assert capsys.readouterr().out.strip().endswith("online")
+
+
+class TestBotRunnerMount:
+    """The bots' view of the extensions tree.
+
+    Three files have to agree before a bot shipped by an extension
+    stacklet can run: core's manifest renders the host path, core's
+    compose mounts it, and the runner scans the container path. Nothing
+    reports it when one of them drifts. The bot just never appears.
+    """
+
+    def test_core_mounts_the_path_the_framework_renders(self):
+        import tomllib
+
+        manifest = tomllib.loads((CORE / "stacklet.toml").read_text())
+        rendered = manifest["env"]["defaults"]["EXTENSIONS_DIR"]
+        assert rendered == "{extension_mount}"
+        assert "${EXTENSIONS_DIR}:" in (CORE / "docker-compose.yml").read_text()
+
+    def test_the_runner_scans_where_compose_mounts(self):
+        import re
+
+        compose = (CORE / "docker-compose.yml").read_text()
+        mounted = re.search(r"\$\{EXTENSIONS_DIR\}:(/[^\s:]+)", compose).group(1)
+        assert str(_runner().EXTENSIONS_DIR) == mounted
+
+    def test_a_bot_is_found_in_either_tree(self, tmp_path):
+        repo, extensions = tmp_path / "stacklets", tmp_path / "extensions"
+        (repo / "docs" / "bot").mkdir(parents=True)
+        (extensions / "drive" / "bot").mkdir(parents=True)
+        roots = (repo, extensions)
+
+        bot_dir_for = _runner().bot_dir_for
+        assert bot_dir_for("docs", roots) == repo / "docs" / "bot"
+        assert bot_dir_for("drive", roots) == extensions / "drive" / "bot"
+
+    def test_the_repo_tree_wins(self, tmp_path):
+        """Same rule as discovery: an extension never shadows a release."""
+        repo, extensions = tmp_path / "stacklets", tmp_path / "extensions"
+        (repo / "docs" / "bot").mkdir(parents=True)
+        (extensions / "docs" / "bot").mkdir(parents=True)
+
+        found = _runner().bot_dir_for("docs", (repo, extensions))
+        assert found == repo / "docs" / "bot"

From 35626af98b3e24e5f9f7bfd0c00caf05337193a3 Mon Sep 17 00:00:00 2001
From: Arthur <hello@arthware.dev>
Date: Sun, 20 Sep 2026 13:51:24 +0200
Subject: [PATCH 04/11] docs: add RFC-002 on installation, instances and
 updates

Describe the limitations of the current git checkout install model and
the options for packaging, updates and multiple instances per Mac.

Rewrite the update procedure in the admin guide:

- switch between release tags instead of running `git pull`
- stash local changes before switching, and recover from conflicts
- do not run `git pull origin main`, which moves the instance to
  unreleased code

Remove `./stack updates` from the operator docs. The command does not
exist.

Also write `[core] name` to `stack.toml` during installation.
---
 docs/README.md                                |   7 +-
 docs/admin-guide.md                           |  87 ++++-
 ...-002-installation-instances-and-updates.md | 297 ++++++++++++++++++
 docs/agent/ops.md                             |  17 +-
 lib/stack/installer_v2.py                     |   3 +
 5 files changed, 403 insertions(+), 8 deletions(-)
 create mode 100644 docs/adr/rfc-002-installation-instances-and-updates.md

diff --git a/docs/README.md b/docs/README.md
index 8a0e7d1c..cd0f91e3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -21,4 +21,9 @@
 - [ADR-007](adr/adr-007-port-convention.md) 42xxx port convention
 - [ADR-008](adr/adr-008-convention-based-bot-runner.md) Convention-based bot runner
 - [ADR-009](adr/adr-009-managed-ai-provider.md) Managed AI with oMLX as default
-- [RFC-001](adr/rfc-001-dashboard-and-companion-apps.md) Dashboard and companion apps
\ No newline at end of file
+- [ADR-010](adr/adr-010-event-pipeline.md) Event pipeline
+- [ADR-011](adr/adr-011-vault-brain-projection.md) Vault to brain projection
+- [ADR-012](adr/adr-012-nanobot-fork.md) nanobot fork
+- [ADR-013](adr/adr-013-stacklet-locations-and-stages.md) Stacklet locations and stages
+- [RFC-001](adr/rfc-001-dashboard-and-companion-apps.md) Dashboard and companion apps
+- [RFC-002](adr/rfc-002-installation-instances-and-updates.md) Installation, instances and updates
\ No newline at end of file
diff --git a/docs/admin-guide.md b/docs/admin-guide.md
index e61f69e7..cbe2a5b7 100644
--- a/docs/admin-guide.md
+++ b/docs/admin-guide.md
@@ -828,16 +828,91 @@ Stash the tarball on a USB stick or in 1Password.
 
 Container images update themselves nightly at 3am via Watchtower. You do nothing for that.
 
-For the famstack code itself:
+The famstack code is a git checkout, and a release is a tag. Updating means moving your checkout to a newer tag.
 
 ```bash
-git pull
-./stack restart <stacklet>    # for any stacklet whose code changed
+cd ~/famstack
+git fetch --tags
+git tag | tail -5              # what is available
+git checkout v0.3.0-beta.3     # the one you want
+./stack doctor
+```
+
+Then restart what the release touched. This prints the list:
+
+```bash
+git diff --name-only v0.3.0-beta.2 v0.3.0-beta.3 -- stacklets/ | cut -d/ -f2 | sort -u
+```
+
+Restart any of those you run. If the same command against `lib/` prints anything, the framework itself changed and everything wants a restart:
+
+```bash
+./stack down all && ./stack up all
+```
+
+Nothing in the update touches your instance. `stack.toml`, `users.toml`, `.stack/`, `~/famstack-data/` and `~/famstack-extensions/` are all outside git's reach, so your config, secrets, data and your own stacklets come through a tag switch untouched.
+
+### If you have edited files in the checkout
+
+git refuses to move while one of your edits is in the way:
+
+```
+error: Your local changes to the following files would be overwritten by checkout:
+	stacklets/docs/docker-compose.yml
+Please commit your changes or stash them before you switch branches.
+Aborting
+```
+
+Set them aside, switch, put them back:
+
+```bash
+git stash
+git checkout v0.3.0-beta.3
+git stash pop
+```
+
+If the release did not touch the same file, `git stash pop` re-applies your edit and you are done.
+
+If the release changed the same lines, it reports a conflict and **keeps your stash**, so nothing is lost:
+
+```
+CONFLICT (content): Merge conflict in stacklets/docs/docker-compose.yml
+The stash entry is kept in case you need it again.
+```
+
+From there, look at what your edit was, then keep it or drop it:
+
+```bash
+git stash show -p                    # your change
+
+# keep it: edit the file to merge both sides, then
+git add stacklets/docs/docker-compose.yml && git stash drop
+
+# or take the release's version and give up your edit
+git checkout HEAD -- stacklets/docs/docker-compose.yml && git stash drop
 ```
 
-If `git pull` shows changes to `lib/stack/` or to a stacklet you are running, restart that stacklet. If in doubt, restart everything.
+Editing a shipped stacklet means doing this on every update. There is no override mechanism: a stacklet in `~/famstack-extensions/` can add to what famstack ships, not replace it. If your change is one other families would want, an issue or a pull request costs you less in the long run.
+
+### Knowing where you are
+
+```bash
+git describe --tags        # v0.3.0-beta.3, or a tag plus commits past it
+```
+
+Checking out a tag leaves you in "detached HEAD". That is normal and nothing to repair, but it does mean `git pull` no longer works:
+
+```
+$ git pull
+You are not currently on a branch.
+Please specify which branch you want to merge with.
+```
+
+Do not take git's suggestion to run `git pull origin main`. It succeeds, and it quietly moves you off releases onto unreleased development code while `./stack version` carries on reporting the last release number. Use `git fetch --tags` and `git checkout <tag>`.
+
+If you cloned and never checked out a tag, you are on `main`, which is development. `git pull` there gives you unreleased work rather than the next release. `git fetch --tags && git checkout <tag>` moves you onto releases.
 
-Pre-1.0 caveat: occasionally a release changes a config schema or env var. Release notes will say so. Read them before pulling.
+Pre-1.0 caveat: occasionally a release changes a config schema or env var. Release notes say so. Read them before updating.
 
 ### Paperless-ngx 3.x (docs stacklet)
 
@@ -848,7 +923,7 @@ This release moves the `docs` stacklet from Paperless-ngx 2.20.15 to 3.0.4.
 ```bash
 ./stack down docs
 tar -czf ~/docs-pre-3x-backup.tar.gz -C ~/famstack-data docs
-git pull
+git fetch --tags && git checkout v0.3.0-beta.3
 ./stack up docs
 ```
 
diff --git a/docs/adr/rfc-002-installation-instances-and-updates.md b/docs/adr/rfc-002-installation-instances-and-updates.md
new file mode 100644
index 00000000..7fe20522
--- /dev/null
+++ b/docs/adr/rfc-002-installation-instances-and-updates.md
@@ -0,0 +1,297 @@
+# RFC-002: Installation, Instances and Updates
+
+## Status
+Draft. No decision taken. Written after the extension-stacklets work surfaced
+how much of the instance lives inside the code tree.
+
+## Context
+
+Today one directory is four things at once:
+
+| Role | What lives there |
+|---|---|
+| The product | `lib/stack/`, `stacklets/`, `docs/` |
+| The installation | the git checkout you run `./stack` from |
+| The instance | `stack.toml`, `users.toml`, `.stack/secrets.toml`, setup markers |
+| The git repo | `main`, tags, your local edits |
+
+Data is already out (`~/famstack-data/`), and extension stacklets are now out
+(`~/famstack-extensions/`). Everything else is entangled.
+
+Updating, as documented in the admin guide:
+
+```bash
+git pull
+./stack restart <stacklet>    # for any stacklet whose code changed
+```
+
+Container images update on a separate track: Watchtower pulls nightly at 3am
+for every container whose stacklet declares `[upstream] channel = "patch"`,
+which is the default (`lib/stack/stack.py:542`).
+
+## The problems, precisely
+
+**P1. You cannot install a release.** The README says `git clone`, which puts
+you on `main`. Reaching `v0.3.0-beta.3` means `git checkout v0.3.0-beta.3`,
+which detaches HEAD, after which `git pull` no longer does what the admin
+guide says it does. There is no `stack update`. Five tags exist and nothing in
+the product knows about them.
+
+**P2. The version string is a constant in the working tree.**
+`VERSION = "0.3.0-beta.3"` (`lib/stack/cli.py:197`) is what `stack version`
+and `stack status` report, next to a short SHA. On a `main` checkout between
+tags that number is simply the last one someone typed, so it names a hundred
+different trees.
+
+**P3. A release does not describe what runs.** Across the stacklets there are
+19 image references. Exactly one is pinned to an exact upstream version
+(`paperless-ngx:3.0.4`). Five are `:latest` (element-web, synapse, tika,
+adguard, watchtower), one is `:main` (open-webui), one carries no tag at all
+(openedai-speech-min), five float on a major or minor (`forgejo:14`,
+`postgres:16-alpine`, `valkey:8-alpine`, `gotenberg:8`, `caddy:2-alpine`), and
+Immich takes `${IMMICH_VERSION:-release}`. Two people installing the same tag
+a month apart run different software, and neither can say which.
+
+**P4. Two update channels that do not know about each other.** Watchtower
+moves images nightly; git moves code when the admin remembers. The Paperless
+3.x incident is written up in the admin guide: Watchtower rolled instances
+from 2.20 to 3.0 across a major version while the code that configures it
+stayed behind, and the documented recovery is a backup most people do not
+have. That is the failure mode of two uncoordinated channels, not a
+Paperless-specific accident.
+
+**P5. Nothing migrates.** There is no migration code anywhere in `lib/stack/`.
+A release that changes a config key, a secret name or a data layout relies on
+the admin reading release notes. A live example found while writing this: the
+installer's `write_stack_toml()` never wrote `[core] name`, so every instance
+it has ever created calls itself "stack" rather than "famstack". That is
+cosmetic until something derives a path from it, which the extensions work
+just did. New installs are fixed; every existing instance still has the old
+file and nothing tells it.
+
+**P6. Nothing knows whether the running system matches the checkout.** The
+admin guide's instruction is "if in doubt, restart everything". `stack doctor`
+already compares each container's environment against freshly rendered env and
+reports drift, which is the right shape; it just has no equivalent for image
+digests or code.
+
+**P7. Documented commands that do not exist.** `docs/agent/ops.md` listed
+`./stack updates`. There is no such command. The row is gone, and both the
+operator docs and the admin guide now describe the real tag-to-tag procedure,
+including the stash dance a local edit forces.
+
+## What "proper" would mean
+
+Four pillars, in dependency order:
+
+1. **A versioned artifact.** Installing names a version, and that version says
+   what runs, including image digests.
+2. **A stable on-disk layout.** An instance lives somewhere an upgrade cannot
+   touch, so the artifact can be replaced wholesale.
+3. **An update command.** One verb: fetch, show what changes, migrate, apply,
+   verify, and say what it restarted.
+4. **Instance identity.** Every runtime name derives from an instance, so more
+   than one can coexist.
+
+Pillars 2 and 4 are the same refactor seen from two angles. That is the
+central claim of this document: **moving instance state out of the code tree
+unlocks packaging, safe updates and multiple instances at once.** Everything
+else is downstream of it.
+
+## Option space: what we ship
+
+### A. Git checkout plus `stack update` (evolve what we have)
+
+`stack update` fetches tags, shows the release notes for the delta, checks out
+the tag, runs migrations, restarts what changed, and runs `doctor`.
+
+- **For:** days of work, not weeks. Keeps clone-and-hack, which is the
+  contributor funnel. No packaging infrastructure, no signing, no formula.
+  Rollback is `git checkout <previous tag>` for the code half.
+- **Against:** the admin still needs git and a toolchain. A dirty working tree
+  blocks the update, which we have to handle in prose. It cannot be
+  unattended, because a checkout can conflict.
+
+### B. Homebrew tap
+
+`brew install famstack-dev/tap/famstack`, then `brew upgrade famstack`.
+
+- **For:** the native macOS answer for a macOS-only product. Homebrew is
+  already a hard prerequisite, so it adds no new dependency. Versioning,
+  rollback and uninstall come for free. `brew upgrade` is a verb people
+  already run.
+- **Against:** we maintain a formula per release. The prefix is replaced on
+  upgrade, so pillar 2 is a hard prerequisite rather than a nice-to-have. A
+  hacked stacklet inside the prefix is destroyed by the next upgrade, so the
+  dev path has to be explicitly supported (`STACK_DIR` plus a `--root`).
+
+### C. PyPI wheel plus pipx
+
+- **For:** `pip install famstack` is familiar, and the CLI is stdlib-only so a
+  wheel is trivial. Needs `[build-system]` and `[project.scripts]`, neither of
+  which exists today.
+- **Against:** buys nothing over Homebrew on a macOS-only product, and adds a
+  Python-version matrix we do not want. The stacklets tree is data (compose
+  files, hooks executed from disk, taxonomy), which fits a wheel badly.
+
+### D. Signed tarball and a `curl | sh` installer
+
+- **For:** total control over layout and upgrade, no third-party index.
+- **Against:** we own the updater, the signing and eventually notarization.
+  This is the most work for the least differentiation, and `curl | sh` is a
+  hard sell to the privacy-minded audience this product is for.
+
+**Recommendation:** A now, B as the mainstream path once pillar 2 lands. Not
+C. D only if we ever ship something that must be notarized.
+
+## Multi-instance: what is actually in the way
+
+Config isolation already exists: `STACK_DIR` points the CLI at a different
+`stack.toml`, `users.toml` and `.stack/` while sharing one stacklets tree
+(`lib/stack/cli.py find_instance_dir`). The integration rig uses it.
+
+Runtime isolation does not exist. Every name below is machine-global:
+
+| Resource | Where it is fixed |
+|---|---|
+| Compose project and `container_name` (`stack-<id>`) | every `docker-compose.yml` |
+| Docker network `stack` | `lib/stack/docker.py:117` |
+| Service ports 42xxx | each `stacklet.toml` |
+| Host API port 42001 | `stacklets/core/famstack-api.py:34` (env-overridable, but the launchd wrapper does not set it) |
+| launchd label `dev.famstack.api` | `stacklets/core/hooks/on_start.py:11` |
+| launchd label `dev.famstack.whisper` | `stacklets/ai/hooks/on_install.py:39` |
+| The user's crontab entry | backup stacklet hooks |
+| `omlx` via Homebrew and `~/.omlx/models` | machine-wide by nature |
+
+One subtler than the rest: `project_states()` (`lib/stack/docker.py:254`) maps
+any compose project named `stack-*` to a stacklet id. A second instance would
+report the first instance's containers as its own, so `stack list` lies before
+anything collides.
+
+This is why `tests/integration/stacktests` takes the dev instance down rather
+than running beside it, and why the operator docs say two instances cannot run
+on one Mac.
+
+**Honest read on demand:** the only real consumers today are the test rig and
+a developer wanting dev beside prod. A household needs one instance. An office
+deployment might want more, and that is the question to answer before building
+the UX.
+The namespacing prep is worth doing anyway, because `project_states()`
+cross-talk is a correctness bug waiting for the first person who tries.
+
+## Recommended path
+
+Each phase stands alone and ships on its own. Gates are what proves it.
+
+### Phase 0: make a release installable (days)
+
+- Install instructions clone and check out the latest tag.
+- `stack update`: fetch tags, print the delta's release notes, stash a dirty
+  tree or refuse, check out, restart stacklets whose files changed, run
+  doctor, and put the stash back with the conflict path spelled out.
+- `stack version` reports the checkout's tag, the SHA, and whether the tree is
+  dirty or behind.
+- ~~Delete `./stack updates` from ops.md or implement it.~~ Done: the row is
+  removed and the manual procedure is documented, which is what `stack update`
+  has to automate.
+
+*Gate:* on the rig, from `v0.3.0-beta.2`, `stack update` lands on beta.3,
+restarts exactly the stacklets that changed, and `stack doctor` is clean.
+
+### Phase 1: instance state leaves the code tree (the enabling refactor)
+
+- `stack.toml`, `users.toml` and `.stack/` move to `~/.famstack/<instance>/`,
+  or `~/Library/Application Support/famstack/<instance>/`.
+- `STACK_DIR` stays the override; the default stops being the checkout.
+- `stack migrate` moves an existing instance and prints what it did.
+- A checkout that still holds a `stack.toml` fails loudly and names the
+  command, rather than silently running a half-migrated instance. Pre-1.0
+  says no compatibility shims; a one-shot migration with a hard cut honours
+  that better than a fallback path.
+
+*Gate:* a fresh clone at a new path, pointed at a migrated instance, brings
+the whole stack up with no state in the checkout. `git clean -xdf` in the
+checkout destroys nothing but build artifacts.
+
+### Phase 2: a release describes what runs (days, independent of 1)
+
+- Pin every image to an exact upstream version, as `docs` already is.
+- Watchtower keeps running, but against exact tags it can only deliver digest
+  rebuilds, never a major jump.
+- A release manifest (`versions.toml` or generated from the compose files)
+  lists the image set for that tag, and `stack doctor` compares what is
+  running against it.
+
+*Gate:* two fresh installs of the same tag, a month apart, produce the same
+image digests. The Paperless failure mode cannot recur without a code change.
+
+### Phase 3: migrations (weeks)
+
+- `schema_version` in `stack.toml`, a `migrations/` directory, and `stack
+  update` applying them in order before restarting anything.
+- Forward-only. Say so plainly: Paperless proved that a data migration is not
+  reversible, so the safety net is backups, not rollback.
+- Which makes backup coverage (Postgres dumps, not just files) a prerequisite
+  for any unattended updater.
+
+*Gate:* an instance created by today's installer, with no `[core] name`, is
+migrated by `stack update` and ends up identical to a fresh install.
+
+### Phase 4: packaged artifact (weeks, needs 1 and 3)
+
+Homebrew tap. `brew upgrade famstack` replaces the prefix; the instance is
+untouched because of Phase 1; migrations run on the next `stack` invocation
+because of Phase 3.
+
+*Gate:* `brew install`, `brew upgrade`, `brew uninstall` leave a working
+instance, an upgraded instance, and an instance whose data survived.
+
+### Phase 5: instance namespacing (weeks, only on demand)
+
+Derive every runtime name from an instance id: compose project prefix,
+network, port offsets, launchd labels, API port. Scope `project_states()` to
+the instance's own prefix. Add `stack --instance <name>` and a registry.
+
+*Gate:* two instances up at once on one Mac, each `stack list` reporting only
+its own containers, both reachable.
+
+## Pros and cons versus today's model
+
+| | Today (git checkout) | Proposed (Phases 0 to 4) |
+|---|---|---|
+| Install | `git clone`, one command, no packaging work | `brew install`, or clone for contributors |
+| What you get | whatever `main` is at that minute | a named version with a known image set |
+| Update | `git pull` plus manual restarts by feel | one command that migrates, restarts and verifies |
+| Rollback | `git checkout` for code; data is one-way regardless | same, but stated honestly and backed by backups |
+| Hackability | edit anything in the tree, it takes effect | preserved via a dev checkout; the packaged prefix is read-only |
+| Instance state | inside the checkout, gitignored | outside it, survives any reinstall |
+| Multi-instance | config only, runtime collides | possible, once namespaced |
+| Cost to us | zero | a formula per release, a migration per schema change, image pins to maintain |
+| Risk | drift nobody can see | a wrong migration hits every instance at once |
+
+The honest summary: today's model is cheap for us and fine for someone who
+reads release notes. It fails the person who installed once in March, let
+Watchtower run, and now cannot say what they are running or how to move to
+the current tag. That person is the target audience.
+
+## Non-goals and risks
+
+- **Do not break clone-and-hack.** It is how contributors arrive and how
+  stacklet authors work. Any packaged path keeps a documented dev checkout.
+- **Do not promise rollback.** Forward-only with backups is the truthful
+  contract while data migrations are one-way.
+- **Do not build the multi-instance UX before there is demand.** Do the
+  namespacing prep, which is a bug fix either way.
+- **Watchtower's default deserves a product decision.** Nightly auto-update is
+  a real feature for families and it is also what broke Paperless. Exact pins
+  make it safe; keeping floating tags and auto-update is the combination that
+  bites.
+
+## Open questions
+
+1. Is clone-and-hack a supported install path at 1.0, or the contributor path
+   only?
+2. Does an office deployment need several instances per machine, or one per
+   box?
+3. Are we willing to own a Homebrew tap, formula and bottle, per release?
+4. Should Watchtower stay on by default once releases pin exact versions?
diff --git a/docs/agent/ops.md b/docs/agent/ops.md
index c51c9730..ce27f850 100644
--- a/docs/agent/ops.md
+++ b/docs/agent/ops.md
@@ -38,7 +38,6 @@ If a precondition is missing, `./stack` prints exactly what to do. Don't improvi
 | `./stack logs <id>` | yes | no | tail container logs |
 | `./stack errors` | yes | no | recent error logs (24h) |
 | `./stack host` | yes | no | disk / memory / uptime |
-| `./stack updates` | yes | no | checks for newer Docker images |
 | `./stack config [--secrets]` | yes | no | prints resolved config |
 | `./stack ai models` | yes | no | lists installed AI models |
 | `./stack setup ai` | yes | no | re-runs AI install (model swap path) |
@@ -110,6 +109,22 @@ Port collisions: do not silently rebind. Surface them. The user's fix is "stop t
 
 For symptoms not on this table: `./stack logs <id>` + `./stack errors`, paste output to the user. **Do not invent fixes.**
 
+## Updating
+
+A release is a git tag. There is no `stack update`; the admin moves the checkout.
+
+```bash
+git fetch --tags && git checkout <tag> && ./stack doctor
+```
+
+- **What to restart:** `git diff --name-only <old> <new> -- stacklets/ | cut -d/ -f2 | sort -u`. Anything in that list that is running. If the same command against `lib/` prints anything, the framework changed: `./stack down all && ./stack up all`.
+- **Local edits block the switch.** `git stash` → checkout → `git stash pop`. A conflicting pop keeps the stash, so nothing is lost: `git checkout HEAD -- <file> && git stash drop` takes the release's version.
+- **A tag checkout is a detached HEAD.** `git pull` fails there. Never suggest `git pull origin main` as the fix: it succeeds and silently moves the instance onto unreleased code while `./stack version` still reports the last release.
+- **`./stack version` is a constant in the tree,** not the running state. `git describe --tags` is the truth.
+- **The instance survives a tag switch.** Config, secrets, data and `~/<product>-extensions/` are all outside git.
+
+Full prose: [../admin-guide.md](../admin-guide.md) § Updating.
+
 ## Backups
 
 - **`~/famstack-data/`** - mandatory. Time Machine, restic, or rsync. Pick one.
diff --git a/lib/stack/installer_v2.py b/lib/stack/installer_v2.py
index f058a0fb..3f9aec57 100644
--- a/lib/stack/installer_v2.py
+++ b/lib/stack/installer_v2.py
@@ -255,6 +255,9 @@ def write_stack_toml(family_name, server_name, timezone, language="en"):
 # Run 'stack up <stacklet>' after changes to apply them.
 
 [core]
+# Product name. Drives CLI branding and the default paths derived from it
+# (~/<name>-extensions). Without it the instance calls itself "stack".
+name = "famstack"
 stack_owner = "{family_name}"
 domain = ""
 # Hostname used in port-mode URLs and the `{{ip}}` template var. Empty

From 6b9c1335d5f3f36ff85109fbf51e1be323c1da81 Mon Sep 17 00:00:00 2001
From: Arthur <hello@arthware.dev>
Date: Sun, 20 Sep 2026 14:21:04 +0200
Subject: [PATCH 05/11] feat(update): add a command to update to a release

Add `stack update [<tag>]`. It fetches release tags from all remotes,
shows the current and target release, and checks out the target tag.
`--dry-run` shows the plan, `--yes` skips the confirmation.

- No services are restarted. The command lists the stacklets that need
  a restart: running stacklets with changed files, or all running
  stacklets if `lib/` changed.
- Local changes are stashed and re-applied. If they conflict with the
  release, the update is rolled back and the changes are restored.
- A checkout that is already ahead of the newest release is not moved.
- On a branch, the output explains that the tag checkout detaches HEAD
  and how to switch back. On a fork without release tags, the error
  lists the remotes it checked and how to add the upstream remote.
---
 docs/admin-guide.md                           |  60 +++-
 ...-002-installation-instances-and-updates.md |  11 +-
 docs/agent/ops.md                             |  13 +-
 docs/design-notes.md                          |  51 ++++
 lib/stack/cli.py                              | 216 ++++++++++++++
 lib/stack/updater.py                          | 244 +++++++++++++++
 tests/framework/test_updater.py               | 281 ++++++++++++++++++
 7 files changed, 861 insertions(+), 15 deletions(-)
 create mode 100644 lib/stack/updater.py
 create mode 100644 tests/framework/test_updater.py

diff --git a/docs/admin-guide.md b/docs/admin-guide.md
index cbe2a5b7..4270e49c 100644
--- a/docs/admin-guide.md
+++ b/docs/admin-guide.md
@@ -830,18 +830,46 @@ Container images update themselves nightly at 3am via Watchtower. You do nothing
 
 The famstack code is a git checkout, and a release is a tag. Updating means moving your checkout to a newer tag.
 
+```bash
+./stack update
+```
+
+That is the whole thing from v0.3.0-beta.4 onward. It fetches the releases, shows what the jump changes, moves the checkout, and sets your local edits aside and puts them back.
+
+It does not restart anything. New code on disk is not new code running: a stacklet picks up a release when its containers are recreated, and when your family loses a service for thirty seconds is your call, not a side effect of updating. So the command works out which restarts the release actually earns and prints them:
+
+```
+  ✓  Updated to v0.3.0-beta.4
+
+  Restart to pick it up
+    ./stack restart docs
+    ./stack doctor
+```
+
+```bash
+./stack update --dry-run         # show the plan, change nothing
+./stack update v0.3.0-beta.4     # a specific release instead of the newest
+./stack update --yes             # skip the confirmation
+```
+
+A stacklet is named only if the release changed files inside it and it is running, so a documentation release asks for nothing. If the release changed anything under `lib/`, every running stacklet is named, because that is the code they all share.
+
+### Updating by hand
+
+`stack update` ships in v0.3.0-beta.4. Moving *to* that release, or moving between older ones, is the same steps typed out:
+
 ```bash
 cd ~/famstack
 git fetch --tags
 git tag | tail -5              # what is available
-git checkout v0.3.0-beta.3     # the one you want
+git checkout v0.3.0-beta.4     # the one you want
 ./stack doctor
 ```
 
 Then restart what the release touched. This prints the list:
 
 ```bash
-git diff --name-only v0.3.0-beta.2 v0.3.0-beta.3 -- stacklets/ | cut -d/ -f2 | sort -u
+git diff --name-only v0.3.0-beta.3 v0.3.0-beta.4 -- stacklets/ | cut -d/ -f2 | sort -u
 ```
 
 Restart any of those you run. If the same command against `lib/` prints anything, the framework itself changed and everything wants a restart:
@@ -854,6 +882,23 @@ Nothing in the update touches your instance. `stack.toml`, `users.toml`, `.stack
 
 ### If you have edited files in the checkout
 
+`stack update` handles this for you. It lists the files it is about to set aside, warns in advance when one of them is a file the release also changes, and puts them back afterwards.
+
+If they collide, it winds the whole update back: you end up on the release you started from, with your edits exactly where they were and nothing left in the stash. Then it tells you how to go ahead deliberately:
+
+```
+  ⚠  Your edits collide with v0.3.0-beta.4. Nothing changed.
+      Back on v0.3.0-beta.3 with your edits where they were.
+      The collision is in:
+      • stacklets/docs/docker-compose.yml
+      To take the release anyway, deal with that file first:
+      git checkout -- <file>   drop your version for the release's
+      git stash                keep it, then pop and merge by hand
+      then run ./stack update again.
+```
+
+A half-applied update is worse than no update: a compose file with conflict markers in it does not parse, so the services you restart next fail for a reason that has nothing to do with the release. What follows is the same work done by hand, which is what an older release needs.
+
 git refuses to move while one of your edits is in the way:
 
 ```
@@ -910,7 +955,16 @@ Please specify which branch you want to merge with.
 
 Do not take git's suggestion to run `git pull origin main`. It succeeds, and it quietly moves you off releases onto unreleased development code while `./stack version` carries on reporting the last release number. Use `git fetch --tags` and `git checkout <tag>`.
 
-If you cloned and never checked out a tag, you are on `main`, which is development. `git pull` there gives you unreleased work rather than the next release. `git fetch --tags && git checkout <tag>` moves you onto releases.
+If you cloned and never checked out a tag, you are on `main`, which is development. `git pull` there gives you unreleased work rather than the next release. `./stack update` moves you onto the newest release and says so before it does: your branch is left where it is, and `git switch main` goes back to it. If `main` already contains the newest release, which it will if you pulled recently, it tells you that instead of moving you backwards.
+
+**On a fork**, `origin` is your copy and has none of the project's releases in it. `./stack update` fetches tags from every remote, so add the project as one:
+
+```bash
+git remote add upstream https://github.com/famstack-dev/famstack.git
+./stack update
+```
+
+Without it there is nothing to update to, and the command says which remotes it looked at.
 
 Pre-1.0 caveat: occasionally a release changes a config schema or env var. Release notes say so. Read them before updating.
 
diff --git a/docs/adr/rfc-002-installation-instances-and-updates.md b/docs/adr/rfc-002-installation-instances-and-updates.md
index 7fe20522..8a3167bb 100644
--- a/docs/adr/rfc-002-installation-instances-and-updates.md
+++ b/docs/adr/rfc-002-installation-instances-and-updates.md
@@ -185,12 +185,13 @@ Each phase stands alone and ships on its own. Gates are what proves it.
 
 ### Phase 0: make a release installable (days)
 
-- Install instructions clone and check out the latest tag.
-- `stack update`: fetch tags, print the delta's release notes, stash a dirty
-  tree or refuse, check out, restart stacklets whose files changed, run
-  doctor, and put the stash back with the conflict path spelled out.
+- Install instructions clone and check out the latest tag. *(open)*
+- ~~`stack update`: fetch tags, print the delta, stash a dirty tree, check
+  out, restart stacklets whose files changed, run doctor.~~ Shipped. It
+  refuses to restart anything when the stash conflicts, and prints the
+  recovery commands instead.
 - `stack version` reports the checkout's tag, the SHA, and whether the tree is
-  dirty or behind.
+  dirty or behind. *(open: the version is still a constant in the tree)*
 - ~~Delete `./stack updates` from ops.md or implement it.~~ Done: the row is
   removed and the manual procedure is documented, which is what `stack update`
   has to automate.
diff --git a/docs/agent/ops.md b/docs/agent/ops.md
index ce27f850..f9062fc9 100644
--- a/docs/agent/ops.md
+++ b/docs/agent/ops.md
@@ -33,6 +33,7 @@ If a precondition is missing, `./stack` prints exactly what to do. Don't improvi
 | `./stack restart <id>` | yes | no | `down` + `up` |
 | `./stack destroy <id>` | yes | **YES** | removes containers + `~/famstack-data/<id>/` + secrets |
 | `./stack uninstall` | yes | **YES, EVERYTHING** | destroys every stacklet, network, all data, config |
+| `./stack update [<tag>]` | yes | no | moves the checkout to a release; restarts nothing, prints what to restart |
 | `./stack list` | yes | no | reports state |
 | `./stack status` | yes | no | runs health checks |
 | `./stack logs <id>` | yes | no | tail container logs |
@@ -111,14 +112,12 @@ For symptoms not on this table: `./stack logs <id>` + `./stack errors`, paste ou
 
 ## Updating
 
-A release is a git tag. There is no `stack update`; the admin moves the checkout.
+A release is a git tag. `./stack update` moves the checkout to one and restarts what that staled. `--dry-run` shows the plan, `--yes` skips the confirmation, a tag argument picks a release other than the newest.
 
-```bash
-git fetch --tags && git checkout <tag> && ./stack doctor
-```
-
-- **What to restart:** `git diff --name-only <old> <new> -- stacklets/ | cut -d/ -f2 | sort -u`. Anything in that list that is running. If the same command against `lib/` prints anything, the framework changed: `./stack down all && ./stack up all`.
-- **Local edits block the switch.** `git stash` → checkout → `git stash pop`. A conflicting pop keeps the stash, so nothing is lost: `git checkout HEAD -- <file> && git stash drop` takes the release's version.
+- **It never restarts anything.** New code on disk is not new code running; recreating containers is the admin's decision. The command names what the release staled: stacklets it changed *and* that are running, or every running stacklet when anything under `lib/` changed.
+- **Local edits are set aside and put back.** If they collide with the release the whole update winds back: same release as before, edits in place, stash empty. Never leave a tree carrying conflict markers, a compose file with them in it does not parse.
+- **Before v0.3.0-beta.4 there is no `update`.** By hand: `git fetch --tags && git checkout <tag> && ./stack doctor`, then restart what `git diff --name-only <old> <new> -- stacklets/` names.
+- **Works from a branch or a fork.** On `main` it moves to the tag and says the branch is left behind (`git switch main` returns). Tags are fetched from every remote, so a fork needs the project added as a remote or there is nothing to update to.
 - **A tag checkout is a detached HEAD.** `git pull` fails there. Never suggest `git pull origin main` as the fix: it succeeds and silently moves the instance onto unreleased code while `./stack version` still reports the last release.
 - **`./stack version` is a constant in the tree,** not the running state. `git describe --tags` is the truth.
 - **The instance survives a tag switch.** Config, secrets, data and `~/<product>-extensions/` are all outside git.
diff --git a/docs/design-notes.md b/docs/design-notes.md
index 960edb26..6e849176 100644
--- a/docs/design-notes.md
+++ b/docs/design-notes.md
@@ -169,3 +169,54 @@ This is not specific to extensions. Every bind mount built from a variable has
 had it since the first one. The fix, if it is worth one, is for the down path
 to re-render env the way the up path does, which is a change to every
 stacklet's teardown and wants its own commit.
+
+## Customising a shipped stacklet without fighting the updater (2026-09-20)
+
+Writing the update docs made the gap obvious. An admin who wants a different
+Paperless setting, an extra volume, or a second service beside one of ours has
+exactly one move today: edit the file in `stacklets/`. Every update then stops
+on that edit, and they resolve the same conflict again on the next one.
+`~/famstack-extensions/` does not help, because an extension adds a stacklet
+and never replaces one the repo ships. So the only paths we offer are "carry a
+patch forever" or "fork", and both are worse than what the admin wanted.
+
+**Compose already has the answer, and we turned it off.** `docker compose` has
+loaded `docker-compose.override.yml` beside the main file since forever, but
+only when it resolves files itself. `docker.compose()` passes `-f <file>`
+explicitly, which disables that discovery. So the feature exists, is
+understood by every Docker user, and is one argument away:
+
+```
+docker compose -f docker-compose.yml -f docker-compose.override.yml ...
+```
+
+A stacklet's override would live at `stacklets/<id>/docker-compose.override.yml`,
+gitignored like `.env`, hand-written by the admin, and merged by compose with
+its own documented rules. `stack up` picks it up, an update never touches it,
+and `stack doctor` can report that a stacklet is running with one so a
+surprising container is traceable.
+
+**The same `-f` plumbing is what mounting several extension dirs needs.** That
+was left open in [adr-013](adr/adr-013-stacklet-locations-and-stages.md): a
+compose file cannot iterate a list, so only the first extension dir is
+bind-mounted into the bot runner. A framework-generated overlay, written next
+to the base file on every `stack up`, would carry one mount line per configured
+directory. One mechanism, two problems, which is the argument for building it
+properly rather than special-casing either.
+
+Open, and the reason this is a note and not a card yet:
+
+- Compose overrides cover services, volumes, env and ports. They do not cover
+  `stacklet.toml`: `[env.defaults]`, ports the framework renders, health
+  checks, hints. An admin who wants a different `PAPERLESS_OCR_LANGUAGE` is
+  editing an env default, not a compose file. Either the override grows a
+  manifest half (`stacklet.override.toml`), or `stack.toml` grows per-stacklet
+  env overrides, which is arguably where it belongs.
+- Two writers to one path. If the framework generates an overlay for extension
+  mounts and the admin hand-writes one, they collide. Separate names
+  (`docker-compose.override.yml` for the admin, a generated file the framework
+  owns) or a single generated file that includes the admin's, but it has to be
+  decided before either exists.
+- An override is unversioned local state that changes what runs. `stack doctor`
+  should say so out loud, the way it reports env drift, or the next
+  "why is this container different" takes an hour.
diff --git a/lib/stack/cli.py b/lib/stack/cli.py
index 40b9df48..bbe69357 100644
--- a/lib/stack/cli.py
+++ b/lib/stack/cli.py
@@ -1271,6 +1271,215 @@ def handle_uninstall(stck, args):
     print(f"  {DIM}Run 'stack install' to start fresh.{RESET}\n")
 
 
+def handle_update(stck, args):
+    """Move the checkout to a release. Restarting stays the admin's call.
+
+    Sources only: nothing here stops or starts a service. A family is
+    using these, so when they go down is a decision for the person at the
+    keyboard, not a side effect of updating. The command works out which
+    restarts the release actually earns and prints them.
+
+    The move is a transaction. Local edits are set aside and put back,
+    and if they collide with the release the whole thing winds back to
+    where it started, because a half-applied update leaves conflict
+    markers inside files that have to parse.
+    """
+    from .prompt import TEAL, confirm
+    from .updater import (
+        Checkout, latest_tag, restart_targets, touches_framework,
+        touched_stacklets, version_key,
+    )
+
+    checkout = Checkout(stck.root)
+    if not checkout.is_git():
+        print_error({"error": "This is not a git checkout, so there is no release to move to",
+                     "hint": "git clone https://github.com/famstack-dev/famstack.git"})
+        sys.exit(1)
+
+    print("\n  Fetching releases...", file=sys.stderr)
+    fetched, fetch_err = checkout.fetch_tags()
+    if not fetched:
+        print(f"  {ORANGE}\u26a0{RESET}  Could not reach the remote. Working from the tags already here.",
+              file=sys.stderr)
+        if fetch_err:
+            print(f"      {DIM}{fetch_err.splitlines()[-1]}{RESET}", file=sys.stderr)
+
+    tags = checkout.tags()
+    target = args.tag or latest_tag(tags)
+    if not target:
+        print_error({
+            "error": "No releases found in this checkout",
+            "problems": [
+                f"tags come from: {', '.join(checkout.remotes()) or 'no remotes'}",
+                "on a fork, add the project as a remote: "
+                "git remote add upstream <url>",
+            ],
+        })
+        sys.exit(1)
+    if target not in tags:
+        print_error({"error": f"No such release: {target}",
+                     "problems": [f"latest is {latest_tag(tags)}"]})
+        sys.exit(1)
+
+    current = checkout.current_tag()
+    if current == target:
+        print(f"\n  {GREEN}\u2713{RESET}  Already on {TEAL}{target}{RESET}\n")
+        return
+
+    # Working past the newest release: a branch, main, or a tag with
+    # commits after it. Moving "up" to that release would move backwards
+    # and stash whatever is in progress to do it.
+    branch = checkout.branch()
+    if not args.tag and checkout.contains(target):
+        where = f"{branch}, which is development," if branch else checkout.describe()
+        print(f"\n  {GREEN}\u2713{RESET}  {TEAL}{where}{RESET} "
+              f"is already past {target}, the newest release.")
+        print(f"  {DIM}To move onto that release anyway: "
+              f"stack update {target}{RESET}")
+        if len(checkout.remotes()) > 1:
+            print(f"  {DIM}Tags came from: {', '.join(checkout.remotes())}{RESET}")
+        print()
+        return
+
+    # ── What this jump would do ───────────────────────────────────
+    base = current or "HEAD"
+    changed = checkout.changed_paths(base, target)
+    subjects = checkout.log_subjects(base, target)
+    running = docker.running_project_ids()
+    targets = restart_targets(changed, running)
+    dirty = checkout.dirty_paths()
+    collisions = sorted(set(dirty) & set(changed))
+
+    print(f"\n  {BOLD}Update{RESET}  {DIM}{checkout.describe()}{RESET} \u2192 {TEAL}{target}{RESET}\n")
+    if current and version_key(target) < version_key(current):
+        print(f"  {ORANGE}\u26a0{RESET}  {target} is older than {current}. Data does not downgrade.")
+    if subjects:
+        commits = f"{len(subjects)} commit" + ("s" if len(subjects) != 1 else "")
+        files = f"{len(changed)} file" + ("s" if len(changed) != 1 else "")
+        print(f"  {commits}, {files}")
+        for line in subjects[:5]:
+            print(f"  {DIM}\u2022 {line}{RESET}")
+        if len(subjects) > 5:
+            print(f"  {DIM}  ... and {len(subjects) - 5} more{RESET}")
+    if dirty:
+        count = f"{len(dirty)} file" + ("s" if len(dirty) != 1 else "")
+        print(f"\n  Your edits to {count} are set aside for the move, then put back:")
+        for path in dirty[:5]:
+            print(f"  {DIM}\u2022 {path}{RESET}")
+        for path in collisions:
+            print(f"  {ORANGE}\u26a0{RESET}  {path} is also changed by this release. "
+                  f"If they collide, the update winds back and changes nothing.")
+    if branch:
+        print(f"\n  {DIM}This leaves {branch} for the tag, which detaches HEAD. "
+              f"Your work stays on {branch}; git switch {branch} goes back.{RESET}")
+    if targets:
+        scope = ("every running stacklet" if touches_framework(changed)
+                 else ", ".join(targets))
+        print(f"\n  Needs a restart afterwards: {scope}")
+    print(f"  {DIM}Release notes: "
+          f"https://github.com/famstack-dev/famstack/releases/tag/{target}{RESET}")
+
+    if getattr(args, "dry_run", False):
+        _print_restart_advice(targets, changed, running, touches_framework, touched_stacklets)
+        return
+    if not getattr(args, "yes", False):
+        if not sys.stdin.isatty():
+            print_error({"error": "Pass --yes to confirm (non-interactive)"})
+            sys.exit(1)
+        if not confirm(f"Update to {target}?"):
+            print(f"  {DIM}Aborted{RESET}\n")
+            return
+
+    # ── Move ──────────────────────────────────────────────────────
+    was = checkout.position()
+    stashed = checkout.stash() if dirty else False
+    if stashed:
+        print(f"  {GREEN}\u2713{RESET}  Your edits set aside")
+
+    moved, err = checkout.checkout(target)
+    if not moved:
+        if stashed:
+            checkout.stash_pop()
+        print_error({"error": f"Could not move to {target}",
+                     "problems": err.splitlines()[:4]})
+        sys.exit(1)
+
+    # Announced only once the edits are back, because a failed restore
+    # winds the move back and "now on <tag>" would be a lie by then.
+    if stashed and not _restore_edits(checkout, was, target, collisions):
+        sys.exit(1)
+    print(f"  {GREEN}\u2713{RESET}  Now on {target}")
+
+    print(f"\n  {GREEN}\u2713{RESET}  Updated to {TEAL}{target}{RESET}")
+    _print_restart_advice(targets, changed, running, touches_framework, touched_stacklets)
+
+
+def _print_restart_advice(targets, changed, running, touches_framework, touched_stacklets):
+    """What the admin has to run for the new code to be the running code.
+
+    Deliberately advice and not action: a stacklet only picks up a
+    release when its containers are recreated, and that is a decision
+    about when the family loses the service.
+    """
+    if not targets:
+        idle = sorted(touched_stacklets(changed) - set(running))
+        if idle:
+            print(f"\n  {DIM}Nothing to restart. {', '.join(idle)} changed but "
+                  f"is not running, and will pick this up on the next stack up.{RESET}\n")
+        else:
+            print(f"\n  {DIM}Nothing running was changed by this release.{RESET}\n")
+        return
+
+    print(f"\n  {BOLD}Restart to pick it up{RESET}")
+    if touches_framework(changed):
+        print(f"  {DIM}The framework changed, so this is every running stacklet.{RESET}")
+        print(f"    {TEAL}./stack restart all{RESET}")
+    else:
+        for sid in targets:
+            print(f"    {TEAL}./stack restart {sid}{RESET}")
+    print(f"    {TEAL}./stack doctor{RESET}\n")
+
+
+def _restore_edits(checkout, was, target, collisions) -> bool:
+    """Put the admin's edits back, or wind the whole update back.
+
+    git keeps the stash entry when a pop conflicts, so both sides of the
+    collision still exist: the release is the tag, the edits are the
+    stash. That makes undoing safe, and undoing is the right default. A
+    tree carrying conflict markers in a compose file is not something to
+    hand back to someone who typed one command.
+    """
+    from .prompt import TEAL
+
+    restored, _ = checkout.stash_pop()
+    if restored:
+        print(f"  {GREEN}\u2713{RESET}  Your edits put back")
+        return True
+
+    checkout.force_checkout(was)
+    recovered, err = checkout.stash_pop()
+    print(f"\n  {ORANGE}\u26a0{RESET}  Your edits collide with {target}. Nothing changed.")
+
+    if not recovered:
+        print(f"      {RED}The wind-back did not finish.{RESET} Your edits are still "
+              f"in the stash:")
+        print(f"      {DIM}git stash list && git stash pop{RESET}")
+        if err:
+            print(f"      {DIM}{err.splitlines()[-1]}{RESET}\n")
+        return False
+
+    print(f"      Back on {TEAL}{checkout.describe()}{RESET} with your edits where they were.")
+    if collisions:
+        print("      The collision is in:")
+        for path in collisions:
+            print(f"      {DIM}\u2022 {path}{RESET}")
+    print("      To take the release anyway, deal with that file first:")
+    print(f"      {DIM}git checkout -- <file>   drop your version for the release's{RESET}")
+    print(f"      {DIM}git stash                keep it, then pop and merge by hand{RESET}")
+    print(f"      then run {TEAL}./stack update{RESET} again.\n")
+    return False
+
+
 def handle_version(stck, args):
     sha = stck._git_commit()
     print(f"{stck.product_name()} {VERSION} ({sha})")
@@ -1336,6 +1545,7 @@ def _plugin_help(module_path: str):
     "setup": handle_setup,
     "logs": handle_logs,
     "version": handle_version,
+    "update": handle_update,
 }
 
 # ── Help ─────────────────────────────────────────────────────────────────
@@ -1357,6 +1567,7 @@ def _plugin_help(module_path: str):
         ("logs <stacklet>",    "Tail container logs"),
     ]),
     ("Setup", [
+        ("update [<tag>]",     "Move to a release and restart what it changed"),
         ("install",            "Interactive setup wizard"),
         ("uninstall",          "Remove all services, config, and data"),
         ("init",               "Create Docker network and data directories"),
@@ -1450,6 +1661,11 @@ def main():
     p = sub.add_parser("down"); p.add_argument("stacklet")
     p = sub.add_parser("destroy"); p.add_argument("stacklet"); p.add_argument("--yes", action="store_true")
     p = sub.add_parser("restart"); p.add_argument("stacklet")
+    p = sub.add_parser("update")
+    p.add_argument("tag", nargs="?", default=None,
+                   help="Release to move to (default: the newest)")
+    p.add_argument("--dry-run", action="store_true", help="Show what would change")
+    p.add_argument("--yes", action="store_true", help="Skip the confirmation")
     p = sub.add_parser("setup"); p.add_argument("stacklet")
     p = sub.add_parser("env"); p.add_argument("stacklet")
     p = sub.add_parser("logs")
diff --git a/lib/stack/updater.py b/lib/stack/updater.py
new file mode 100644
index 00000000..9b53f31a
--- /dev/null
+++ b/lib/stack/updater.py
@@ -0,0 +1,244 @@
+"""Moving a checkout from one release to the next.
+
+A release is a git tag. Updating is therefore four questions: which tags
+exist, which one are we on, what does the jump change, and what has to be
+restarted because of it. This module answers them. The CLI does the
+talking, the confirming and the restarting.
+
+The awkward part is not git, it is the admin's own edits. A tag switch
+refuses to run over them, so the update sets them aside and puts them
+back, and when the release touched the same lines it has to say so
+clearly rather than leave someone staring at a conflict.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+
+# ── Versions ─────────────────────────────────────────────────────────────
+
+_VERSION_RE = re.compile(
+    r"v?(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)"
+    r"(?:-(?P<label>[0-9A-Za-z]+)(?:\.(?P<num>\d+))?)?$"
+)
+
+
+def version_key(tag: str) -> tuple:
+    """Sort key for a release tag, newest last.
+
+    The tuple has a fixed shape so any two tags compare without raising:
+    a tag that is not a version sorts below every one that is, rather
+    than crashing a listing because someone tagged `nightly`.
+
+    A prerelease ranks below the release it leads to, so `v0.3.0` wins
+    over `v0.3.0-beta.3`, and prerelease numbers compare as numbers, so
+    beta.10 is newer than beta.9.
+    """
+    match = _VERSION_RE.match(tag.strip())
+    if not match:
+        return (0, 0, 0, 0, 0, "", 0)
+    label = match.group("label") or ""
+    return (
+        1,
+        int(match.group("major")),
+        int(match.group("minor")),
+        int(match.group("patch")),
+        0 if label else 1,
+        label,
+        int(match.group("num") or 0),
+    )
+
+
+def is_release(tag: str) -> bool:
+    """Whether a tag names a version this module can order."""
+    return version_key(tag)[0] == 1
+
+
+def latest_tag(tags) -> str | None:
+    """The newest release among these tags, or None if there is none."""
+    releases = [t for t in tags if is_release(t)]
+    return max(releases, key=version_key) if releases else None
+
+
+# ── What a jump makes stale ──────────────────────────────────────────────
+
+def _is_framework(path: str) -> bool:
+    """A path every stacklet depends on, whatever it declares."""
+    return path.startswith("lib/") or path == "stack"
+
+
+def touches_framework(changed_paths) -> bool:
+    """Whether a jump changes code every stacklet runs on."""
+    return any(_is_framework(p) for p in changed_paths)
+
+
+def touched_stacklets(changed_paths) -> set[str]:
+    """The stacklets a jump changes files inside, running or not."""
+    return {
+        p.split("/")[1]
+        for p in changed_paths
+        if p.startswith("stacklets/") and p.count("/") >= 2
+    }
+
+
+def restart_targets(changed_paths, running) -> list[str]:
+    """Which running stacklets a jump leaves stale.
+
+    A stacklet is stale when the release changed a file inside it, and
+    every stacklet is stale when the release changed the framework they
+    all run on. Stacklets that are not running stay that way: they pick
+    the release up whenever they are next started.
+    """
+    if touches_framework(changed_paths):
+        return sorted(running)
+    return sorted(touched_stacklets(changed_paths) & set(running))
+
+
+# ── The checkout ─────────────────────────────────────────────────────────
+
+class Checkout:
+    """The git working tree the stack runs from.
+
+    Every method reports rather than raises, because the caller is a CLI
+    that has to turn a git failure into a sentence an admin can act on.
+    """
+
+    def __init__(self, root: Path):
+        self.root = Path(root)
+
+    def _run(self, *args: str) -> tuple[int, str, str]:
+        result = subprocess.run(
+            ["git", "-C", str(self.root), *args],
+            capture_output=True, text=True, timeout=180,
+        )
+        return result.returncode, result.stdout.strip(), result.stderr.strip()
+
+    # ── Where we are ──
+
+    def is_git(self) -> bool:
+        code, out, _ = self._run("rev-parse", "--is-inside-work-tree")
+        return code == 0 and out == "true"
+
+    def tags(self) -> list[str]:
+        code, out, _ = self._run("tag")
+        return out.splitlines() if code == 0 else []
+
+    def current_tag(self) -> str | None:
+        """The tag HEAD sits exactly on, or None when it sits past one."""
+        code, out, _ = self._run("describe", "--tags", "--exact-match")
+        return out if code == 0 else None
+
+    def describe(self) -> str:
+        """Human position: a tag, a tag plus commits, or a bare SHA."""
+        code, out, _ = self._run("describe", "--tags", "--always")
+        return out if code == 0 else ""
+
+    def contains(self, ref: str) -> bool:
+        """Whether HEAD already includes that ref.
+
+        True for anyone working past the newest release: on a branch, on
+        main, or on a tag with commits after it. Moving them "up" to that
+        release would be a move backwards.
+        """
+        code, _, _ = self._run("merge-base", "--is-ancestor", ref, "HEAD")
+        return code == 0
+
+    def is_dirty(self) -> bool:
+        """Tracked files with uncommitted changes.
+
+        Untracked files do not count. git carries them across a checkout
+        untouched unless the target tag ships a file of the same name, in
+        which case it refuses loudly and the caller relays that.
+        """
+        _, out, _ = self._run("status", "--porcelain", "--untracked-files=no")
+        return bool(out)
+
+    def dirty_paths(self) -> list[str]:
+        """Paths of the tracked files that differ from HEAD.
+
+        Porcelain pads each line with two status columns and a space.
+        Splitting on whitespace rather than slicing a fixed offset keeps
+        the first path intact, whose leading column is a space and is the
+        easiest character in the output to lose.
+        """
+        _, out, _ = self._run("status", "--porcelain", "--untracked-files=no")
+        return [line.split(maxsplit=1)[1] for line in out.splitlines() if line.strip()]
+
+    # ── What changes ──
+
+    def changed_paths(self, old: str, new: str) -> list[str]:
+        code, out, _ = self._run("diff", "--name-only", old, new)
+        return out.splitlines() if code == 0 else []
+
+    def log_subjects(self, old: str, new: str) -> list[str]:
+        code, out, _ = self._run("log", "--format=%s", f"{old}..{new}")
+        return out.splitlines() if code == 0 else []
+
+    # ── Moving ──
+
+    def fetch_tags(self) -> tuple[bool, str]:
+        """Bring in every remote's tags, not just the default remote's.
+
+        A contributor works from a fork, where `origin` is their copy and
+        the releases live on the remote they added. Fetching the default
+        remote would offer them whatever their fork happens to be tagged
+        with, usually nothing, and call it the newest release.
+        """
+        code, _, err = self._run("fetch", "--all", "--tags", "--quiet")
+        return code == 0, err
+
+    def remotes(self) -> list[str]:
+        """Remote names, in the order git lists them."""
+        code, out, _ = self._run("remote")
+        return out.splitlines() if code == 0 else []
+
+    def branch(self) -> str | None:
+        """The branch HEAD is on, or None when detached.
+
+        A tag checkout is detached, and a fresh clone is not. The update
+        has something different to say to each: one is a developer mid
+        work, the other is someone who has never left `main`.
+        """
+        code, out, _ = self._run("symbolic-ref", "--short", "-q", "HEAD")
+        return out if code == 0 and out else None
+
+    def position(self) -> str:
+        """The ref to come back to if the update has to be wound back.
+
+        A branch name when HEAD is on one, so restoring it moves the tree
+        and not the branch pointer. A commit otherwise, which covers both
+        a tag checkout and a detached HEAD past one.
+        """
+        return self.branch() or self._run("rev-parse", "HEAD")[1]
+
+    def force_checkout(self, ref: str) -> tuple[bool, str]:
+        """Restore `ref`, discarding whatever is in the way.
+
+        Only ever used to undo this command's own half-applied move. The
+        admin's edits are in the stash at that point, so what gets thrown
+        away is a conflicted merge of two things we still have.
+        """
+        code, out, err = self._run("checkout", "--force", ref)
+        return code == 0, (err or out)
+
+    def checkout(self, ref: str) -> tuple[bool, str]:
+        code, out, err = self._run("checkout", ref)
+        return code == 0, (err or out)
+
+    def stash(self) -> bool:
+        """Set local edits aside. False when there was nothing to set."""
+        code, out, _ = self._run("stash", "push", "-m", "stack update")
+        return code == 0 and "No local changes" not in out
+
+    def stash_pop(self) -> tuple[bool, str]:
+        """Put them back. On conflict git keeps the entry, so the edit is
+        recoverable and the message says how."""
+        code, out, err = self._run("stash", "pop")
+        return code == 0, "\n".join(part for part in (err, out) if part)
+
+    def has_stash(self) -> bool:
+        _, out, _ = self._run("stash", "list")
+        return bool(out)
diff --git a/tests/framework/test_updater.py b/tests/framework/test_updater.py
new file mode 100644
index 00000000..5f9b9069
--- /dev/null
+++ b/tests/framework/test_updater.py
@@ -0,0 +1,281 @@
+"""Moving a checkout from one release to the next.
+
+A release is a git tag, so an update is: find the tags, work out what the
+jump changes, move the working tree, and restart the stacklets whose files
+moved under them. The reasoning lives in `stack.updater`; this pins it.
+
+The git tests drive a real repository in a temp directory. Git's behaviour
+under a dirty tree is the whole reason this module exists, and a fake would
+only prove that the fake agrees with what we assumed.
+"""
+
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from stack.updater import Checkout, latest_tag, restart_targets, version_key
+
+
+# ── Fixtures ─────────────────────────────────────────────────────────────
+
+def _git(repo: Path, *args: str) -> str:
+    return subprocess.run(["git", "-C", str(repo), *args],
+                          capture_output=True, text=True, check=True).stdout.strip()
+
+
+@pytest.fixture
+def repo(tmp_path):
+    """A checkout with two releases, shaped like the real one.
+
+    v1 ships a `docs` stacklet; v2 changes it, adds `photos`, and touches
+    the framework, so one repository covers every restart case.
+    """
+    root = tmp_path / "checkout"
+    (root / "stacklets" / "docs").mkdir(parents=True)
+    (root / "lib" / "stack").mkdir(parents=True)
+    _git(root.parent, "init", "-q", str(root))
+    _git(root, "config", "user.email", "test@example.com")
+    _git(root, "config", "user.name", "Test")
+
+    (root / "stacklets" / "docs" / "docker-compose.yml").write_text("image: paperless:1\n")
+    (root / "lib" / "stack" / "cli.py").write_text("VERSION = 'v1'\n")
+    _git(root, "add", "-A")
+    _git(root, "commit", "-qm", "first release")
+    _git(root, "tag", "v0.1.0")
+
+    (root / "stacklets" / "docs" / "docker-compose.yml").write_text("image: paperless:2\n")
+    (root / "stacklets" / "photos").mkdir()
+    (root / "stacklets" / "photos" / "stacklet.toml").write_text('id = "photos"\n')
+    (root / "lib" / "stack" / "cli.py").write_text("VERSION = 'v2'\n")
+    _git(root, "add", "-A")
+    _git(root, "commit", "-qm", "second release")
+    _git(root, "tag", "v0.2.0")
+
+    _git(root, "checkout", "-q", "v0.1.0")
+    return root
+
+
+# ── Which tag is the newest ──────────────────────────────────────────────
+
+class TestLatestRelease:
+    """Pre-1.0 tags are mostly prereleases, and they have to sort right."""
+
+    def test_picks_the_highest_version(self):
+        assert latest_tag(["v0.2.1", "v0.3.0", "v0.2.2"]) == "v0.3.0"
+
+    def test_a_release_outranks_its_own_prereleases(self):
+        assert latest_tag(["v0.3.0-beta.3", "v0.3.0"]) == "v0.3.0"
+
+    def test_prereleases_sort_numerically_not_alphabetically(self):
+        """beta.10 is newer than beta.9, which a string sort gets wrong."""
+        tags = ["v0.3.0-beta.9", "v0.3.0-beta.10"]
+        assert latest_tag(tags) == "v0.3.0-beta.10"
+
+    def test_the_real_tag_history_resolves(self):
+        tags = ["v0.2.1", "v0.2.2", "v0.3.0-beta.1", "v0.3.0-beta.2", "v0.3.0-beta.3"]
+        assert latest_tag(tags) == "v0.3.0-beta.3"
+
+    def test_ignores_tags_that_are_not_versions(self):
+        assert latest_tag(["nightly", "v0.1.0", "some-branch-point"]) == "v0.1.0"
+
+    def test_no_versions_at_all(self):
+        assert latest_tag(["nightly"]) is None
+        assert latest_tag([]) is None
+
+    def test_version_order_is_total(self):
+        """Sorting by the key must agree with the intended release order."""
+        ordered = ["v0.2.1", "v0.2.2", "v0.3.0-beta.1", "v0.3.0-beta.2", "v0.3.0"]
+        assert sorted(reversed(ordered), key=version_key) == ordered
+
+
+# ── What has to be restarted ─────────────────────────────────────────────
+
+class TestRestartTargets:
+    """A release only makes a stacklet stale if it changed that stacklet,
+    or changed the framework every stacklet runs on."""
+
+    def test_only_the_stacklets_the_release_touched(self):
+        changed = ["stacklets/docs/docker-compose.yml", "docs/admin-guide.md"]
+        assert restart_targets(changed, running={"docs", "photos"}) == ["docs"]
+
+    def test_a_stacklet_that_is_not_running_is_left_alone(self):
+        changed = ["stacklets/photos/stacklet.toml"]
+        assert restart_targets(changed, running={"docs"}) == []
+
+    def test_a_framework_change_stales_everything_running(self):
+        changed = ["lib/stack/stack.py"]
+        assert restart_targets(changed, running={"docs", "core"}) == ["core", "docs"]
+
+    def test_the_cli_wrapper_counts_as_the_framework(self):
+        assert restart_targets(["stack"], running={"docs"}) == ["docs"]
+
+    def test_a_docs_only_release_restarts_nothing(self):
+        changed = ["README.md", "docs/adr/adr-013.md"]
+        assert restart_targets(changed, running={"docs", "core"}) == []
+
+
+# ── The checkout itself ──────────────────────────────────────────────────
+
+class TestCheckout:
+    """Everything that talks to git, against a real repository."""
+
+    def test_reads_its_tags_and_position(self, repo):
+        co = Checkout(repo)
+        assert co.is_git()
+        assert set(co.tags()) == {"v0.1.0", "v0.2.0"}
+        assert co.current_tag() == "v0.1.0"
+
+    def test_knows_when_it_is_not_on_a_release(self, repo):
+        _git(repo, "checkout", "-q", "-b", "work")
+        (repo / "new.txt").write_text("x")
+        _git(repo, "add", "-A")
+        _git(repo, "commit", "-qm", "past the tag")
+
+        assert Checkout(repo).current_tag() is None
+
+    def test_knows_when_a_release_is_already_behind_it(self, repo):
+        """A developer on a branch, or anyone on main, is past the newest
+        tag. Offering to move them backwards onto it would stash their
+        work to deliver an older stack, so the caller has to be able to
+        tell the difference."""
+        co = Checkout(repo)
+        assert co.contains("v0.1.0") is True, "HEAD is v0.1.0"
+        assert co.contains("v0.2.0") is False, "v0.2.0 is ahead"
+
+        co.checkout("v0.2.0")
+        assert co.contains("v0.1.0") is True
+        assert co.contains("v0.2.0") is True
+
+    def test_reports_what_a_jump_changes(self, repo):
+        co = Checkout(repo)
+        changed = co.changed_paths("v0.1.0", "v0.2.0")
+
+        assert "stacklets/docs/docker-compose.yml" in changed
+        assert "stacklets/photos/stacklet.toml" in changed
+        assert restart_targets(changed, running={"docs"}) == ["docs"]
+
+    def test_reports_the_commits_in_between(self, repo):
+        assert Checkout(repo).log_subjects("v0.1.0", "v0.2.0") == ["second release"]
+
+    def test_moves_the_working_tree(self, repo):
+        co = Checkout(repo)
+        ok, err = co.checkout("v0.2.0")
+
+        assert ok, err
+        assert co.current_tag() == "v0.2.0"
+        assert "paperless:2" in (repo / "stacklets/docs/docker-compose.yml").read_text()
+
+    def test_a_clean_tree_needs_no_stash(self, repo):
+        assert Checkout(repo).is_dirty() is False
+
+    def test_an_edited_file_makes_it_dirty(self, repo):
+        (repo / "stacklets/docs/docker-compose.yml").write_text("image: mine\n")
+        assert Checkout(repo).is_dirty() is True
+
+    def test_names_the_files_it_will_stash(self, repo):
+        """The plan lists them, so a truncated path is a lie the admin
+        cannot check. `git status --porcelain` pads with the status
+        columns, and the first line's padding is easy to lose."""
+        (repo / "stacklets/docs/docker-compose.yml").write_text("image: mine\n")
+        (repo / "lib/stack/cli.py").write_text("VERSION = 'mine'\n")
+
+        assert Checkout(repo).dirty_paths() == [
+            "lib/stack/cli.py",
+            "stacklets/docs/docker-compose.yml",
+        ]
+
+    def test_stash_and_pop_round_trip(self, repo):
+        co = Checkout(repo)
+        (repo / "stacklets/docs/docker-compose.yml").write_text("image: mine\n")
+
+        assert co.stash() is True
+        assert co.is_dirty() is False
+        ok, err = co.stash_pop()
+
+        assert ok, err
+        assert (repo / "stacklets/docs/docker-compose.yml").read_text() == "image: mine\n"
+
+    def test_a_conflicting_pop_keeps_the_stash(self, repo):
+        """The case that decides whether this command can be trusted: the
+        admin edited the same file the release changed. git keeps the
+        stash, so the edit is recoverable, and the caller must say so."""
+        co = Checkout(repo)
+        (repo / "stacklets/docs/docker-compose.yml").write_text("image: mine\n")
+        co.stash()
+        assert co.checkout("v0.2.0")[0] is True
+
+        ok, err = co.stash_pop()
+
+        assert ok is False
+        assert "conflict" in err.lower()
+        assert co.has_stash() is True
+
+    def test_knows_the_ref_to_come_back_to(self, repo):
+        """On a branch that is the branch, so a revert restores the tree
+        without moving the branch pointer. Detached, it is the commit."""
+        co = Checkout(repo)
+        assert co.position() == co._run("rev-parse", "HEAD")[1]
+
+        _git(repo, "checkout", "-q", "-b", "work")
+        assert co.position() == "work"
+
+    def test_a_conflicting_pop_can_be_wound_all_the_way_back(self, repo):
+        """The transaction. When the admin's edit and the release collide,
+        the update puts everything back rather than leaving a tree with
+        conflict markers in files that have to parse."""
+        co = Checkout(repo)
+        was = co.position()
+        (repo / "stacklets/docs/docker-compose.yml").write_text("image: mine\n")
+        co.stash()
+        co.checkout("v0.2.0")
+        ok, _ = co.stash_pop()
+        assert ok is False, "this edit is meant to conflict"
+
+        co.force_checkout(was)
+        restored, err = co.stash_pop()
+
+        assert restored, err
+        assert co.current_tag() == "v0.1.0", "back on the release we started on"
+        assert (repo / "stacklets/docs/docker-compose.yml").read_text() == "image: mine\n"
+        assert co.has_stash() is False, "nothing left behind to clean up"
+        assert "<<<<<<<" not in (repo / "stacklets/docs/docker-compose.yml").read_text()
+
+    def test_knows_whether_it_is_on_a_branch(self, repo):
+        """A tag checkout is detached; a clone someone just made is not.
+        The update says different things to each."""
+        co = Checkout(repo)
+        assert co.branch() is None, "the fixture sits on a tag"
+
+        _git(repo, "checkout", "-q", "-b", "work")
+        assert co.branch() == "work"
+
+    def test_tags_come_from_every_remote_not_just_origin(self, repo, tmp_path):
+        """The fork case. Someone who forked has an origin without the
+        project's releases in it, and the releases they want live on the
+        upstream remote they added. Fetching only origin would offer
+        them whatever their fork was tagged with, which is usually
+        nothing, and call that the newest release.
+        """
+        fork = tmp_path / "fork.git"
+        upstream = tmp_path / "upstream.git"
+        _git(repo, "clone", "--bare", "-q", str(repo), str(fork))
+        _git(repo, "clone", "--bare", "-q", str(repo), str(upstream))
+        _git(Path(upstream), "tag", "v9.9.9")
+
+        # Exactly the shape a contributor has: origin is their fork, and
+        # the releases are on the remote they added. With one remote git
+        # would pick it regardless, which is why both exist here.
+        _git(repo, "remote", "add", "origin", str(fork))
+        _git(repo, "remote", "add", "upstream", str(upstream))
+
+        co = Checkout(repo)
+        assert "v9.9.9" not in co.tags()
+        ok, err = co.fetch_tags()
+
+        assert ok, err
+        assert "v9.9.9" in co.tags(), "a release on the upstream remote is invisible"
+        assert latest_tag(co.tags()) == "v9.9.9"
+
+    def test_a_directory_that_is_not_a_checkout(self, tmp_path):
+        assert Checkout(tmp_path).is_git() is False

From b00daf011e19f1979f9e17d73e2834aaa7741979 Mon Sep 17 00:00:00 2001
From: Arthur <hello@arthware.dev>
Date: Sun, 20 Sep 2026 15:11:25 +0200
Subject: [PATCH 06/11] feat(cli): detect stacklets that run outdated code

Label each container with the commit it was started from
(`stack.commit`) during `stack up`.

- `stack list` marks stacklets whose containers run an older commit.
- `stack doctor` reports them.
- `stack restart` without arguments restarts only those stacklets.

Containers without the label are reported as unknown.

Upgrade: containers created before this release have no label. Run
`./stack restart all` once, or restart each stacklet when convenient.
---
 docs/agent/dev.md                     |   4 +
 docs/agent/ops.md                     |   7 +-
 lib/stack/cli.py                      | 104 +++++++++++++++++++++++---
 lib/stack/docker.py                   |  36 +++++++++
 lib/stack/doctor.py                   |  31 +++++++-
 lib/stack/prompt.py                   |  18 +++--
 lib/stack/stack.py                    |  54 +++++++++++--
 lib/stack/updater.py                  |  24 ++++++
 stacklets/agent/docker-compose.yml    |   1 +
 stacklets/ai/docker-compose.yml       |   1 +
 stacklets/chatai/docker-compose.yml   |   1 +
 stacklets/code/docker-compose.yml     |   1 +
 stacklets/core/docker-compose.yml     |   2 +
 stacklets/docs/docker-compose.yml     |   5 ++
 stacklets/infra/docker-compose.yml    |   2 +
 stacklets/memory/docker-compose.yml   |   2 +
 stacklets/messages/docker-compose.yml |   3 +
 stacklets/photos/docker-compose.yml   |   4 +
 tests/framework/test_doctor.py        |  37 +++++++++
 tests/framework/test_updater.py       |  52 ++++++++++++-
 20 files changed, 359 insertions(+), 30 deletions(-)

diff --git a/docs/agent/dev.md b/docs/agent/dev.md
index 1da268bc..0f7f31c5 100644
--- a/docs/agent/dev.md
+++ b/docs/agent/dev.md
@@ -417,6 +417,10 @@ Pre-tag gate, in order. A published tag is never moved; anything missed here shi
 5. Stale references updated: README version callouts, docs links, blog "Try it" instructions.
 6. Tag (`vX.Y.Z` / `vX.Y.Z-beta.N`, annotated), push main + tag, publish the GitHub release with Highlights and an "Upgrading from" section.
 
+**The tag format is load-bearing.** `stack update` parses `v?MAJOR.MINOR.PATCH[-label.N]` and ignores anything else, so a tag spelled `v0.3.0.beta1` is invisible: `stack update` would keep offering the previous release and never mention it. Hyphen before the label, dot before its number, as SemVer has it. The prerelease sorts below the release it leads to, and label numbers compare as numbers, so `beta.10` is newer than `beta.9`.
+
+Two spellings of the same version exist by necessity: the tag and `lib/stack/cli.py VERSION` are SemVer (`0.3.0-beta.3`), while `pyproject.toml` is PEP 440 (`0.3.0b3`), because Python packaging requires it. Step 2 bumps both.
+
 ## Pre-1.0 conventions
 
 - Invariant changes (marker semantics, field renames, contract shifts) get coherent commits - each stands alone for revert.
diff --git a/docs/agent/ops.md b/docs/agent/ops.md
index f9062fc9..a0bc5065 100644
--- a/docs/agent/ops.md
+++ b/docs/agent/ops.md
@@ -30,7 +30,7 @@ If a precondition is missing, `./stack` prints exactly what to do. Don't improvi
 | `./stack up <id>` | yes | no | starts containers, renders `.env`, runs hooks |
 | `./stack down <id>` | yes | no | stops containers; data preserved |
 | `./stack down all` | yes | no | stops every running stacklet in reverse dep order |
-| `./stack restart <id>` | yes | no | `down` + `up` |
+| `./stack restart [<id>]` | yes | no | `down` + `up`; with no argument, only the stacklets running stale code |
 | `./stack destroy <id>` | yes | **YES** | removes containers + `~/famstack-data/<id>/` + secrets |
 | `./stack uninstall` | yes | **YES, EVERYTHING** | destroys every stacklet, network, all data, config |
 | `./stack update [<tag>]` | yes | no | moves the checkout to a release; restarts nothing, prints what to restart |
@@ -45,7 +45,7 @@ If a precondition is missing, `./stack` prints exactly what to do. Don't improvi
 
 **Output contract:** every command returns JSON when piped or when `--json` is passed. Force human output with `--pretty`. Exit code 0 == success.
 
-**Applying config/compose changes to a running stacklet:** `stack up <id>` is the apply command — it re-renders `.env` and `compose up` creates new services and recreates changed ones, leaving the rest running. `restart` (= `down` + `up`) also works but takes the whole stacklet down first. Plain `docker compose restart` does neither: it won't re-render env or create new services.
+**Applying config/compose changes to a running stacklet:** `stack up <id>` is the apply command — it re-renders `.env` and recreates that stacklet's containers. It force-recreates unconditionally (`docker.py compose_up`), because compose's config hash does not cover `env_file` *contents*, so a plain `up -d` would leave a container on stale env. That makes `up` and `restart` (= `down` + `up`) similar in cost; `restart` stops everything first and runs the stop hooks. Plain `docker compose restart` does neither: it won't re-render env or create new services.
 
 ## Invariants
 
@@ -112,9 +112,10 @@ For symptoms not on this table: `./stack logs <id>` + `./stack errors`, paste ou
 
 ## Updating
 
-A release is a git tag. `./stack update` moves the checkout to one and restarts what that staled. `--dry-run` shows the plan, `--yes` skips the confirmation, a tag argument picks a release other than the newest.
+A release is a git tag. `./stack update` moves the checkout to one and names what that staled; `./stack restart` with no argument then restarts exactly those. `--dry-run` shows the plan, `--yes` skips the confirmation, a tag argument picks a release other than the newest.
 
 - **It never restarts anything.** New code on disk is not new code running; recreating containers is the admin's decision. The command names what the release staled: stacklets it changed *and* that are running, or every running stacklet when anything under `lib/` changed.
+- **`./stack restart` with no argument applies it.** Every container is stamped at `stack up` with the commit it started from (`stack.commit`), so `stack list` and `stack doctor` report a stacklet running code the checkout has moved past, and a bare `restart` restarts those. A container with no stamp is reported as unknown, never guessed about.
 - **Local edits are set aside and put back.** If they collide with the release the whole update winds back: same release as before, edits in place, stash empty. Never leave a tree carrying conflict markers, a compose file with them in it does not parse.
 - **Before v0.3.0-beta.4 there is no `update`.** By hand: `git fetch --tags && git checkout <tag> && ./stack doctor`, then restart what `git diff --name-only <old> <new> -- stacklets/` names.
 - **Works from a branch or a fork.** On `main` it moves to the tag and says the branch is left behind (`git switch main` returns). Tags are fetched from every remote, so a fork needs the project added as a remote or there is nothing to update to.
diff --git a/lib/stack/cli.py b/lib/stack/cli.py
index bbe69357..669424f3 100644
--- a/lib/stack/cli.py
+++ b/lib/stack/cli.py
@@ -671,7 +671,12 @@ def print_list(result: dict, stck=None) -> None:
     sha = stck._git_commit() if stck else ""
     version_info = f"  {DIM}{VERSION} ({sha}){RESET}" if sha else ""
     print(f"  {result.get('online', 0)}/{result.get('total', 0)} online{version_info}")
-    print(f"  {DIM}stack up <id> to start a stacklet{RESET}\n")
+    stale = result.get("stale", [])
+    if stale:
+        print_restart_call_to_action(stale)
+        print()
+    else:
+        print(f"  {DIM}stack up <id> to start a stacklet{RESET}\n")
 
 
 def print_status(result: dict) -> None:
@@ -904,6 +909,7 @@ def missing_secrets(stacklet_id):
         docker.container_env,
         docker.image_env,
         missing_secrets=missing_secrets,
+        stale=stck.list().get("stale", []),
     )
 
     print()
@@ -1044,6 +1050,12 @@ def handle_logs(stck, args):
 def handle_restart(stck, args):
     cli = CLI(stck)
 
+    # No argument: restart exactly what is running code the checkout has
+    # moved past. `all` stays the sledgehammer for when you want the lot.
+    if not args.stacklet:
+        _restart_stale(stck, cli, yes=getattr(args, "yes", False))
+        return
+
     if args.stacklet == "all":
         # Whole-stack restart: stop everything running, then bring up
         # every installed stacklet. The two phases use their own
@@ -1074,6 +1086,57 @@ def handle_restart(stck, args):
         print_up_success(result, stck)
 
 
+def _restart_stale(stck, cli, yes=False):
+    """Restart the stacklets whose containers predate the code on disk.
+
+    Only the ones it can prove: a container stamped with the commit it
+    was started from. A stacklet whose containers carry no stamp is left
+    running and named, because silently skipping it is how someone
+    concludes the update was applied when it was not.
+    """
+    from .prompt import TEAL, confirm
+
+    listing = stck.list()
+    stale = listing.get("stale", [])
+    running = {s["id"] for s in listing["stacklets"] if s.get("online") or s.get("starting")}
+    unknown = sorted(running - set(stale) - set(docker.container_commits()))
+
+    if not stale:
+        print(f"\n  {GREEN}\u2713{RESET}  Everything running is on the current code.")
+        if unknown:
+            print(f"  {DIM}Cannot tell for: {', '.join(unknown)}. "
+                  f"Run stack up <id> if you changed its config.{RESET}")
+        print()
+        return
+
+    print(f"\n  {BOLD}Restarting{RESET} {TEAL}{', '.join(stale)}{RESET} "
+          f"{DIM}(running code the checkout has moved past){RESET}")
+    if unknown:
+        print(f"  {DIM}Not touched, no commit stamp to compare: "
+              f"{', '.join(unknown)}{RESET}")
+    print()
+
+    if not yes and sys.stdin.isatty():
+        if not confirm(f"Restart {len(stale)} stacklet(s)?"):
+            print(f"  {DIM}Aborted{RESET}\n")
+            return
+
+    failed = []
+    for sid in stale:
+        print(f"  Restarting {TEAL}{sid}{RESET}...", file=sys.stderr)
+        cli.down(sid)
+        result = cli.up(sid)
+        if "error" in result:
+            failed.append(sid)
+            print(f"  {RED}\u2717{RESET} {sid}: {result['error']}")
+        else:
+            print(f"  {GREEN}\u2713{RESET} {sid}: restarted")
+
+    print()
+    if failed:
+        sys.exit(1)
+
+
 def handle_setup(stck, args):
     stacklet = stck._find_stacklet(args.stacklet)
     if not stacklet:
@@ -1414,6 +1477,25 @@ def handle_update(stck, args):
     _print_restart_advice(targets, changed, running, touches_framework, touched_stacklets)
 
 
+def print_restart_call_to_action(targets, framework=False) -> None:
+    """The one loud line that says the code moved and nothing applied it.
+
+    Printed wherever the gap is visible: after an update, under a list
+    that shows stale stacklets. Same wording every time, because an
+    operator should recognise it rather than read it twice.
+    """
+    from .prompt import TEAL
+
+    print(f"\n  {ORANGE}{BOLD}\u26a0  Code updated. A RESTART is required "
+          f"to apply it.{RESET}")
+    if framework:
+        print(f"     {DIM}The framework changed, so this is everything running.{RESET}")
+        print(f"     {TEAL}./stack restart{RESET}")
+        return
+    print(f"     {TEAL}./stack restart{RESET}  "
+          f"{DIM}or: {', '.join('./stack restart ' + t for t in targets[:3])}{RESET}")
+
+
 def _print_restart_advice(targets, changed, running, touches_framework, touched_stacklets):
     """What the admin has to run for the new code to be the running code.
 
@@ -1430,14 +1512,8 @@ def _print_restart_advice(targets, changed, running, touches_framework, touched_
             print(f"\n  {DIM}Nothing running was changed by this release.{RESET}\n")
         return
 
-    print(f"\n  {BOLD}Restart to pick it up{RESET}")
-    if touches_framework(changed):
-        print(f"  {DIM}The framework changed, so this is every running stacklet.{RESET}")
-        print(f"    {TEAL}./stack restart all{RESET}")
-    else:
-        for sid in targets:
-            print(f"    {TEAL}./stack restart {sid}{RESET}")
-    print(f"    {TEAL}./stack doctor{RESET}\n")
+    print_restart_call_to_action(targets, framework=touches_framework(changed))
+    print(f"     {TEAL}./stack doctor{RESET}\n")
 
 
 def _restore_edits(checkout, was, target, collisions) -> bool:
@@ -1554,7 +1630,7 @@ def _plugin_help(module_path: str):
     ("Lifecycle", [
         ("up <stacklet>|all",      "Start a stacklet (or 'all' to bring up every installed stacklet)"),
         ("down <stacklet>|all",    "Stop a running stacklet (or 'all' to stop everything running)"),
-        ("restart <stacklet>|all", "Restart stacklet (includes env update; 'all' restarts the whole stack)"),
+        ("restart [<stacklet>]",   "Restart what is running stale code (or one stacklet, or 'all')"),
         ("setup <stacklet>",   "Re-run first-time setup (backend detection, accounts, etc.)"),
         ("destroy <stacklet>", "Remove containers, data, and secrets (Destructive operation)"),
     ]),
@@ -1567,7 +1643,7 @@ def _plugin_help(module_path: str):
         ("logs <stacklet>",    "Tail container logs"),
     ]),
     ("Setup", [
-        ("update [<tag>]",     "Move to a release and restart what it changed"),
+        ("update [<tag>]",     "Move the checkout to a release (says what to restart)"),
         ("install",            "Interactive setup wizard"),
         ("uninstall",          "Remove all services, config, and data"),
         ("init",               "Create Docker network and data directories"),
@@ -1660,7 +1736,11 @@ def main():
                    help="(ai) start without the voice container (TTS + Whisper); sets STACK_AI_NO_VOICE=1")
     p = sub.add_parser("down"); p.add_argument("stacklet")
     p = sub.add_parser("destroy"); p.add_argument("stacklet"); p.add_argument("--yes", action="store_true")
-    p = sub.add_parser("restart"); p.add_argument("stacklet")
+    p = sub.add_parser("restart")
+    p.add_argument("stacklet", nargs="?", default=None,
+                   help="Stacklet to restart, 'all', or nothing for whatever "
+                        "is running stale code")
+    p.add_argument("--yes", action="store_true", help="Skip the confirmation")
     p = sub.add_parser("update")
     p.add_argument("tag", nargs="?", default=None,
                    help="Release to move to (default: the newest)")
diff --git a/lib/stack/docker.py b/lib/stack/docker.py
index 8766bf39..b1bf9eed 100644
--- a/lib/stack/docker.py
+++ b/lib/stack/docker.py
@@ -400,6 +400,42 @@ def running_project_ids() -> set[str]:
     return {sid for sid, state in states.items() if state in ("running", "starting")}
 
 
+def container_commits() -> dict[str, str]:
+    """The commit each stacklet's running containers were started from.
+
+    Read from the `stack.commit` label the framework stamps at `stack up`.
+    The key names the framework rather than any product built on it, the
+    same way `STACK_*` env vars and the "stacklet" vocabulary do.
+
+    A container without the label is left out rather than guessed about:
+    it predates the label, or belongs to a service with no labels block,
+    and an unknown answer is not a finding.
+
+    One label per stacklet. Containers of the same stacklet are created
+    together, so they agree in every state except a restart in progress.
+    """
+    try:
+        r = _docker(
+            "ps", "--filter", "label=stack.commit",
+            "--format", '{{.Names}}\t{{.Label "stack.commit"}}',
+            capture_output=True, text=True, timeout=10,
+        )
+        if r.returncode != 0:
+            return {}
+    except Exception:
+        return {}
+
+    commits: dict[str, str] = {}
+    for line in r.stdout.strip().splitlines():
+        name, _, commit = line.partition("\t")
+        commit = commit.strip()
+        parts = name.split("-")
+        if not commit or commit == "unknown" or len(parts) < 2 or parts[0] != "stack":
+            continue
+        commits.setdefault(parts[1], commit)
+    return commits
+
+
 def all_project_ids() -> set[str]:
     """Convenience wrapper — all stacklet IDs with any container state."""
     return set(project_states().keys())
diff --git a/lib/stack/doctor.py b/lib/stack/doctor.py
index 4366f327..17646bc6 100644
--- a/lib/stack/doctor.py
+++ b/lib/stack/doctor.py
@@ -30,6 +30,9 @@
 _RUNTIME_KEYS = frozenset({
     "PATH", "HOSTNAME", "HOME", "TERM", "LANG", "LC_ALL",
     "PYTHON_VERSION", "PYTHONUNBUFFERED", "GPG_KEY",
+    # Stamped per container so staleness can be detected. It differs by
+    # design after any commit, and check_stale_code reports that.
+    "STACK_COMMIT",
 })
 
 
@@ -158,6 +161,25 @@ def check_missing_secrets(stacklet: str, missing: list[str]) -> Finding | None:
     )
 
 
+def check_stale_code(stacklet: str) -> Finding:
+    """A stacklet whose containers predate the code on disk.
+
+    Not a fault, a gap: someone updated the sources and the containers
+    still run what they were started with. Nothing else reports it,
+    because from Docker's side nothing is wrong.
+    """
+    return Finding(
+        title=f"{stacklet} is running code from before the last update",
+        detail=(
+            "Its containers were started from an earlier commit than the one "
+            "checked out. New code on disk is not new code running until the "
+            "containers are recreated."
+        ),
+        fix=f"stack restart {stacklet}",
+        level=WARN,
+    )
+
+
 def check_endpoint(name: str, url: str, reachable: bool) -> Finding | None:
     """A configured endpoint that does not answer.
 
@@ -176,14 +198,16 @@ def check_endpoint(name: str, url: str, reachable: bool) -> Finding | None:
 
 
 def diagnose(stacklets, rendered_env, containers_for, container_env,
-             image_env, *, missing_secrets=None) -> list[Finding]:
+             image_env, *, missing_secrets=None, stale=()) -> list[Finding]:
     """Run every check across the given stacklets.
 
     The collaborators are injected rather than imported so the whole walk
     is testable with plain dicts - no Docker, no instance. Each is a
     callable taking a stacklet id (or container name) and returning facts.
     `missing_secrets` is optional so a caller that has no secret store to
-    consult still gets the container checks.
+    consult still gets the container checks. `stale` names the stacklets
+    whose containers predate the code on disk, which only a caller with a
+    git checkout can work out.
 
     A stacklet whose env cannot be rendered is skipped rather than fatal:
     one misconfigured stacklet should not stop the others being diagnosed,
@@ -197,6 +221,9 @@ def diagnose(stacklets, rendered_env, containers_for, container_env,
             # instance, so its missing credentials are not yet a problem.
             continue
 
+        if stacklet in stale:
+            findings.append(check_stale_code(stacklet))
+
         if missing_secrets:
             found = check_missing_secrets(stacklet, missing_secrets(stacklet))
             if found:
diff --git a/lib/stack/prompt.py b/lib/stack/prompt.py
index 3b7e9e49..a4474142 100644
--- a/lib/stack/prompt.py
+++ b/lib/stack/prompt.py
@@ -96,16 +96,20 @@ def bullet(text):
 # ── Status list ───────────────────────────────────────────────────────────────
 
 def stage_badge(s):
-    """Trailing marker for a stacklet line: the stage it claims.
+    """Trailing markers for a stacklet line: stage, and stale code.
 
-    A stable stacklet carries none, so a normal list reads exactly as it
-    did. Anything else is the stacklet saying it is unfinished, which an
-    operator needs before reading anything into its state.
+    A stable, current stacklet carries none, so a normal list reads
+    exactly as it did. The two that show are what an operator needs
+    before reading anything into the state: a stacklet saying it is
+    unfinished, and one running code the checkout has moved past.
     """
+    parts = []
     stage = s.get("stage", "stable")
-    if not stage or stage == "stable":
-        return ""
-    return f"  {ORANGE}{stage}{RESET}"
+    if stage and stage != "stable":
+        parts.append(f"{ORANGE}{stage}{RESET}")
+    if s.get("stale"):
+        parts.append(f"{ORANGE}restart pending{RESET}")
+    return "  " + " ".join(parts) if parts else ""
 
 
 def status_list(stacklets):
diff --git a/lib/stack/stack.py b/lib/stack/stack.py
index 7ade9f3c..3bf27751 100644
--- a/lib/stack/stack.py
+++ b/lib/stack/stack.py
@@ -192,11 +192,11 @@ def extension_dirs(self) -> list[Path]:
 
         `[core] extension_dirs` takes a list, searched in the order given
         (a bare string is read as a one-entry list). The default is a
-        single directory in the admin's home, named after the product:
-        `~/famstack-extensions`. It is deliberately outside both the repo
-        and the data dir. The repo is replaced on upgrade and would take
-        the admin's code with it; the data dir is what running services
-        write, not where source belongs.
+        single directory in the admin's home named after the product,
+        `~/<[core] name>-extensions`. It is deliberately outside both the
+        repo and the data dir. The repo is replaced on upgrade and would
+        take the admin's code with it; the data dir is what running
+        services write, not where source belongs.
 
         Nothing creates it. An instance with no extensions simply has no
         such directory, and discovery skips what is not there.
@@ -542,6 +542,12 @@ def env(self, stacklet_id: str) -> dict:
         channel = manifest.get("upstream", {}).get("channel", "patch")
         rendered["WATCHTOWER_ENABLE"] = "true" if channel == "patch" else "false"
 
+        # Stamped onto every container as the `stack.commit` label, so what a
+        # container was started from can be compared with the code on
+        # disk. Containers keep their labels from creation time, which is
+        # what makes the comparison mean anything.
+        rendered["STACK_COMMIT"] = self._git_commit()
+
         # Port bind IP — 0.0.0.0 in port mode (LAN-reachable),
         # 127.0.0.1 in domain mode (only Caddy reaches containers)
         rendered["PORT_BIND_IP"] = "127.0.0.1" if self._cfg("core", "domain") else "0.0.0.0"
@@ -594,6 +600,8 @@ def list(self) -> dict:
                     s["degraded"] = True
                     s["health_issues"].append(check.get("hint") or f"{check['url']} not reachable")
 
+        self._mark_stale(stacklets)
+
         online = [s for s in stacklets if s["online"] and not s["degraded"]]
         set_up = [s for s in stacklets if s["enabled"]]
 
@@ -602,12 +610,48 @@ def list(self) -> dict:
             "total": len(stacklets),
             "enabled": len(set_up),
             "online": len(online),
+            "stale": sorted(s["id"] for s in stacklets if s.get("stale")),
             # Every entry carries its own `source` and `path`; these are
             # the directories the extension ones were loaded from, for a
             # caller that wants to name them without deriving them.
             "extension_dirs": [str(d) for d in self.extension_dirs],
         }
 
+    def _mark_stale(self, stacklets: list[dict]) -> None:
+        """Flag the running stacklets whose code the checkout has moved past.
+
+        The comparison is between the commit a container was started from
+        and the commits since, using the same rule a release uses to
+        decide what it staled. A container with no stamp, or a checkout
+        that is not a git tree, simply answers nothing.
+        """
+        from .updater import Checkout, stale_stacklets
+
+        for s in stacklets:
+            s["stale"] = False
+
+        running = {s["id"] for s in stacklets if s["online"] or s["starting"]}
+        if not running:
+            return
+
+        checkout = Checkout(self.root)
+        if not checkout.is_git():
+            return
+
+        seen: dict[str, list[str]] = {}
+
+        def changes_since(commit: str) -> list[str]:
+            """One git call per distinct commit, not per stacklet."""
+            if commit not in seen:
+                seen[commit] = checkout.changed_paths(commit, "HEAD")
+            return seen[commit]
+
+        from .docker import container_commits
+
+        stale = set(stale_stacklets(container_commits(), running, changes_since))
+        for s in stacklets:
+            s["stale"] = s["id"] in stale
+
     def status(self) -> dict:
         """Full system status: version, runtime, host, stacklets."""
         from .cli import VERSION
diff --git a/lib/stack/updater.py b/lib/stack/updater.py
index 9b53f31a..b425a06a 100644
--- a/lib/stack/updater.py
+++ b/lib/stack/updater.py
@@ -97,6 +97,30 @@ def restart_targets(changed_paths, running) -> list[str]:
     return sorted(touched_stacklets(changed_paths) & set(running))
 
 
+def stale_stacklets(revisions, running, changes_since) -> list[str]:
+    """Running stacklets whose code the checkout has moved past.
+
+    `revisions` maps a stacklet id to the commit its containers were
+    built from, read from the OCI `org.opencontainers.image.revision`
+    label. A stacklet is stale when commits since then changed files
+    inside it or under `lib/`, which is the same rule a release uses:
+    anything looser nags about a release that never touched it.
+
+    A stacklet with no revision is left alone. Containers built before
+    the label existed, or from an upstream image that carries someone
+    else's revision, cannot answer the question, and an unknown answer
+    is not a problem to report.
+    """
+    stale = []
+    for stacklet_id in sorted(running):
+        revision = revisions.get(stacklet_id)
+        if not revision:
+            continue
+        if restart_targets(changes_since(revision), {stacklet_id}):
+            stale.append(stacklet_id)
+    return stale
+
+
 # ── The checkout ─────────────────────────────────────────────────────────
 
 class Checkout:
diff --git a/stacklets/agent/docker-compose.yml b/stacklets/agent/docker-compose.yml
index 607b6428..2dd518c3 100644
--- a/stacklets/agent/docker-compose.yml
+++ b/stacklets/agent/docker-compose.yml
@@ -17,6 +17,7 @@ services:
     image: stack-agent:local
     labels:
       - "com.centurylinklabs.watchtower.enable=false"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     extra_hosts:
diff --git a/stacklets/ai/docker-compose.yml b/stacklets/ai/docker-compose.yml
index e936790c..2f332c1a 100644
--- a/stacklets/ai/docker-compose.yml
+++ b/stacklets/ai/docker-compose.yml
@@ -19,6 +19,7 @@ services:
     profiles: ["voice"]
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     ports:
diff --git a/stacklets/chatai/docker-compose.yml b/stacklets/chatai/docker-compose.yml
index 411e9b9a..31053e3a 100644
--- a/stacklets/chatai/docker-compose.yml
+++ b/stacklets/chatai/docker-compose.yml
@@ -15,6 +15,7 @@ services:
     image: ghcr.io/open-webui/open-webui:main
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     extra_hosts:
diff --git a/stacklets/code/docker-compose.yml b/stacklets/code/docker-compose.yml
index bb213d6e..1d14fdde 100644
--- a/stacklets/code/docker-compose.yml
+++ b/stacklets/code/docker-compose.yml
@@ -15,6 +15,7 @@ services:
     image: codeberg.org/forgejo/forgejo:14
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     ports:
diff --git a/stacklets/core/docker-compose.yml b/stacklets/core/docker-compose.yml
index b971f61d..a8b37b01 100644
--- a/stacklets/core/docker-compose.yml
+++ b/stacklets/core/docker-compose.yml
@@ -30,6 +30,7 @@ services:
     container_name: stack-core-bot-runner
     labels:
       - "com.centurylinklabs.watchtower.enable=false"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     extra_hosts:
@@ -69,6 +70,7 @@ services:
     container_name: stack-core-tools
     labels:
       - "com.centurylinklabs.watchtower.enable=false"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     extra_hosts:
diff --git a/stacklets/docs/docker-compose.yml b/stacklets/docs/docker-compose.yml
index ff7c7676..716e5664 100644
--- a/stacklets/docs/docker-compose.yml
+++ b/stacklets/docs/docker-compose.yml
@@ -23,6 +23,7 @@ services:
     image: ghcr.io/paperless-ngx/paperless-ngx:3.0.4
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     depends_on:
@@ -72,6 +73,7 @@ services:
     image: postgres:16-alpine
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     environment:
@@ -92,6 +94,7 @@ services:
     image: docker.io/valkey/valkey:8-alpine
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     healthcheck:
@@ -106,6 +109,7 @@ services:
     image: gotenberg/gotenberg:8
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     command:
@@ -119,6 +123,7 @@ services:
     image: apache/tika:latest
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     restart: unless-stopped
diff --git a/stacklets/infra/docker-compose.yml b/stacklets/infra/docker-compose.yml
index 1cd79dc1..ff27dc75 100644
--- a/stacklets/infra/docker-compose.yml
+++ b/stacklets/infra/docker-compose.yml
@@ -22,6 +22,7 @@ services:
     restart: unless-stopped
     labels:
       - "com.centurylinklabs.watchtower.enable=true"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     ports:
@@ -46,6 +47,7 @@ services:
     restart: unless-stopped
     labels:
       - "com.centurylinklabs.watchtower.enable=true"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     ports:
diff --git a/stacklets/memory/docker-compose.yml b/stacklets/memory/docker-compose.yml
index 7252d2ea..0ad741dd 100644
--- a/stacklets/memory/docker-compose.yml
+++ b/stacklets/memory/docker-compose.yml
@@ -26,6 +26,7 @@ services:
     # version is pinned in the Dockerfile and bumped by hand.
     labels:
       - "com.centurylinklabs.watchtower.enable=false"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     # Read-only: the wiki is a pure view. Quartz renders the brain
@@ -78,6 +79,7 @@ services:
     # Locally-built image — nothing for Watchtower to pull.
     labels:
       - "com.centurylinklabs.watchtower.enable=false"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     extra_hosts:
diff --git a/stacklets/messages/docker-compose.yml b/stacklets/messages/docker-compose.yml
index 8d0e2cef..464db686 100644
--- a/stacklets/messages/docker-compose.yml
+++ b/stacklets/messages/docker-compose.yml
@@ -17,6 +17,7 @@ services:
     image: matrixdotorg/synapse:latest
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     volumes:
@@ -35,6 +36,7 @@ services:
     image: postgres:16-alpine
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     environment:
@@ -56,6 +58,7 @@ services:
     image: vectorim/element-web:latest
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     volumes:
diff --git a/stacklets/photos/docker-compose.yml b/stacklets/photos/docker-compose.yml
index 2f77b2cc..2654b6b5 100644
--- a/stacklets/photos/docker-compose.yml
+++ b/stacklets/photos/docker-compose.yml
@@ -15,6 +15,7 @@ services:
     image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     volumes:
@@ -38,6 +39,7 @@ services:
     image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     # Apple Silicon note: Immich ML runs on CPU here — GPU acceleration via
     # Metal is not yet supported in the Docker image. Still fast enough for
     # face recognition and CLIP search on M-series chips.
@@ -58,6 +60,7 @@ services:
     image: docker.io/valkey/valkey:8-alpine
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     healthcheck:
@@ -69,6 +72,7 @@ services:
     image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
     labels:
       - "com.centurylinklabs.watchtower.enable=${WATCHTOWER_ENABLE:-true}"
+      - "stack.commit=${STACK_COMMIT:-unknown}"
     networks:
       - stack
     environment:
diff --git a/tests/framework/test_doctor.py b/tests/framework/test_doctor.py
index ca8cc302..3008db97 100644
--- a/tests/framework/test_doctor.py
+++ b/tests/framework/test_doctor.py
@@ -13,6 +13,7 @@
     check_env_drift,
     check_exited,
     check_missing_secrets,
+    check_stale_code,
     compose_supplied,
     diagnose,
     env_drift,
@@ -45,6 +46,42 @@ def _fixture_instance():
 
 # ── env_drift ────────────────────────────────────────────────────────────
 
+class TestStaleCode:
+    """A stacklet whose containers predate the code on disk.
+
+    Doctor's findings are built by hand, so a Finding whose fields do not
+    match the dataclass only fails when a real instance has that problem.
+    This one did: it shipped with `is_error=` instead of `level=` and blew
+    up on the rig the first time a stacklet went stale.
+    """
+
+    def test_reports_the_stacklet_and_how_to_apply_it(self):
+        finding = check_stale_code("core")
+
+        assert "core" in finding.title
+        assert finding.fix == "stack restart core"
+
+    def test_is_a_warning_not_an_error(self):
+        """Nothing is broken. The code on disk just is not running yet,
+        so doctor should not exit non-zero over it."""
+        assert check_stale_code("core").is_error is False
+
+    def test_diagnose_raises_one_per_stale_stacklet(self):
+        findings = diagnose(
+            ["docs", "photos"],
+            lambda s: {},
+            lambda s: [{"name": f"stack-{s}", "state": "running",
+                        "exit_code": 0, "since": ""}],
+            lambda n: {},
+            lambda n: {},
+            stale=["docs"],
+        )
+
+        titles = [f.title for f in findings]
+        assert any("docs is running code" in t for t in titles)
+        assert not any("photos is running code" in t for t in titles)
+
+
 def test_detects_the_realm_drift_that_broke_the_bots():
     # The real incident: stack.toml re-seeded to a new realm, container still
     # carrying the old one, every bot login 403ing against a realm that no
diff --git a/tests/framework/test_updater.py b/tests/framework/test_updater.py
index 5f9b9069..771bd3d3 100644
--- a/tests/framework/test_updater.py
+++ b/tests/framework/test_updater.py
@@ -14,7 +14,9 @@
 
 import pytest
 
-from stack.updater import Checkout, latest_tag, restart_targets, version_key
+from stack.updater import (
+    Checkout, latest_tag, restart_targets, stale_stacklets, version_key,
+)
 
 
 # ── Fixtures ─────────────────────────────────────────────────────────────
@@ -115,6 +117,54 @@ def test_a_docs_only_release_restarts_nothing(self):
         assert restart_targets(changed, running={"docs", "core"}) == []
 
 
+# ── Running code versus code on disk ─────────────────────────────────────
+
+class TestStaleStacklets:
+    """After an update the sources have moved and the containers have not.
+
+    Same rule as a release: a stacklet is stale when commits since the one
+    its containers were built from changed files inside it, or the
+    framework every stacklet shares. Anything else would nag about a
+    release that had nothing to do with it.
+    """
+
+    def _changes(self, mapping):
+        return lambda commit: mapping.get(commit, [])
+
+    def test_a_stacklet_the_commits_since_did_not_touch_is_fine(self):
+        changes = self._changes({"old": ["stacklets/photos/stacklet.toml"]})
+        assert stale_stacklets({"docs": "old"}, {"docs"}, changes) == []
+
+    def test_a_stacklet_whose_files_moved_is_stale(self):
+        changes = self._changes({"old": ["stacklets/docs/docker-compose.yml"]})
+        assert stale_stacklets({"docs": "old"}, {"docs"}, changes) == ["docs"]
+
+    def test_a_framework_change_stales_every_running_stacklet(self):
+        changes = self._changes({"old": ["lib/stack/stack.py"]})
+        stamps = {"docs": "old", "core": "old"}
+        assert stale_stacklets(stamps, {"docs", "core"}, changes) == ["core", "docs"]
+
+    def test_a_stacklet_with_no_stamp_is_not_guessed_about(self):
+        """Containers from before stamping existed, or a lost marker. An
+        unknown answer is reported as unknown, not as a problem."""
+        changes = self._changes({"old": ["lib/stack/stack.py"]})
+        assert stale_stacklets({}, {"docs"}, changes) == []
+
+    def test_only_running_stacklets_are_considered(self):
+        changes = self._changes({"old": ["lib/stack/stack.py"]})
+        assert stale_stacklets({"docs": "old"}, set(), changes) == []
+
+    def test_containers_started_at_different_commits(self):
+        """Restarting one stacklet and not another is the normal state
+        halfway through applying an update."""
+        changes = self._changes({
+            "old": ["stacklets/docs/docker-compose.yml"],
+            "new": [],
+        })
+        stamps = {"docs": "old", "memory": "new"}
+        assert stale_stacklets(stamps, {"docs", "memory"}, changes) == ["docs"]
+
+
 # ── The checkout itself ──────────────────────────────────────────────────
 
 class TestCheckout:

From e4dd8378d6be2582a16eda45e528e2f54af642b7 Mon Sep 17 00:00:00 2001
From: Arthur <hello@arthware.dev>
Date: Sun, 20 Sep 2026 15:35:07 +0200
Subject: [PATCH 07/11] chore: add tools/init-repo for development setup

Add a script that checks for Python 3.11+ and uv, runs `uv sync`,
installs the language server and sets `core.hooksPath`. It can be run
again safely.

Git does not let a repository enable its own hooks on clone, so the
`lint`, `typecheck` and `test-unit` make targets run
`tools/init-repo --hooks-only` first. An existing `core.hooksPath` is
not changed.
---
 CONTRIBUTING.md   |  14 +++--
 Makefile          |  16 +++++-
 docs/agent/dev.md |   5 +-
 tools/init-repo   | 140 ++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 166 insertions(+), 9 deletions(-)
 create mode 100755 tools/init-repo

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c73a97a2..8f378f23 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,9 +10,13 @@ One entry point, [Homebrew](https://brew.sh), which brings the rest:
 
 ```bash
 brew install uv
-uv sync --extra test
+tools/init-repo
 ```
 
+`tools/init-repo` is the one-time setup for a clone, and is safe to re-run. It checks the two things that otherwise fail confusingly hours later (an old Python, a missing `uv`), creates the test virtualenv, points git at the repo's hooks, and installs the language server binary. Everything it does is local to your clone.
+
+The hooks are the part git cannot do for you: a fresh clone must not be able to run code, so no repo can enable its own hooks on clone. `make test-unit` and `make typecheck` also enable them, so in practice they are on before your first commit either way.
+
 `uv sync` creates `.venv` in the repo root. Nothing needs activating: `uv run` and `uvx` find it, and the type checker is pointed at it by `pyproject.toml`. The `test` extra declares every dependency the test suite needs, including the bot runtime libraries that tests import directly.
 
 The CLI itself depends only on the standard library. Stacklet containers carry their own runtime dependencies, which is why `.venv` will not contain all of them: `nanobot` and `fastapi`, for example, exist only inside their images.
@@ -31,7 +35,7 @@ Neither is a merge gate, and the type checker is not clean today. Run it on what
 
 ## Language server
 
-Agents working in this repo get a language server, so they can ask for a definition or every reference to a symbol instead of grepping for a name and hoping it is unique. Install the binary once:
+Agents working in this repo get a language server, so they can ask for a definition or every reference to a symbol instead of grepping for a name and hoping it is unique. `tools/init-repo` installs the binary; by hand it is:
 
 ```bash
 uv tool install basedpyright
@@ -71,8 +75,10 @@ A bare `make typecheck` reports on `lib`, `stacklets`, `tools` and `hooks`. `tes
 
 All three live in [docs/agent/dev.md](docs/agent/dev.md), which is the canonical reference and stays shorter than a duplicate here would. The short version: `make test-unit` before every commit, module tests over unit tests, feature branches only, never push without asking. Commit subjects are the changelog famstack.dev renders, so they follow `<type>(<scope>): <what the product does now>` and every one has to parse.
 
-Enable the hooks once per clone so lint and the commit convention are checked before a commit exists rather than in CI:
+The hooks check ruff on staged files and the commit subject before a commit exists, rather than in CI. `tools/init-repo` turns them on, as do `make test-unit` and `make typecheck`. To do only that:
 
 ```bash
-git config core.hooksPath hooks
+make hooks                  # or: git config core.hooksPath hooks
 ```
+
+An explicit `core.hooksPath` is never overwritten, so pointing it elsewhere, or nowhere, is respected.
diff --git a/Makefile b/Makefile
index 7b765e20..322017a3 100644
--- a/Makefile
+++ b/Makefile
@@ -4,11 +4,21 @@ PYTEST = uv run --extra test pytest
 
 # Type check the shipped code. Not a gate: read what it says about the files
 # you touched. `uvx basedpyright <paths>` narrows it further.
-typecheck types:
+typecheck types: hooks
 	-uvx basedpyright
 
+# Point git at the repo's own hooks. Git will not do this on clone, by
+# design: a fresh clone must not be able to run code. The nearest honest
+# thing is to do it the first time someone uses the repo's tooling, which
+# is what every target below depends on.
+#
+# Only when unset, so an explicit choice (an absolute path, a different
+# directory, deliberately no hooks) is never overwritten.
+hooks:
+	@tools/init-repo --hooks-only
+
 # Fast unit tests: no Docker. Run before every commit.
-test-unit unit fast test:
+test-unit unit fast test: hooks
 	$(PYTEST) tests/framework tests/stacklets -v --ignore=tests/framework/test_config_to_container.py
 
 # Live demo-rig tests: uses the already-running Simpsons demo instance.
@@ -31,4 +41,4 @@ test-smoke smoke:
 test-all: test-lifecycle
 test-integration: test-e2e
 
-.PHONY: typecheck types test-unit unit fast test test-demo demo-rig demo test-lifecycle container-lifecycle lifecycle test-e2e container-e2e e2e test-smoke smoke test-all test-integration
+.PHONY: hooks typecheck types test-unit unit fast test test-demo demo-rig demo test-lifecycle container-lifecycle lifecycle test-e2e container-e2e e2e test-smoke smoke test-all test-integration
diff --git a/docs/agent/dev.md b/docs/agent/dev.md
index 0f7f31c5..74488575 100644
--- a/docs/agent/dev.md
+++ b/docs/agent/dev.md
@@ -383,8 +383,9 @@ subject is not: it appears in plain-text contexts too, including
 `tools/commit-lint` enforces the header, and is the same check in every
 place that matters: the `commit-msg` hook rejects it before the commit
 exists, CI rejects the PR title and every commit in the PR, and the
-release gate runs it over the range being tagged. Enable the hooks once
-per clone with `git config core.hooksPath hooks`.
+release gate runs it over the range being tagged. `tools/init-repo`
+turns the hooks on, as do `make test-unit` and `make typecheck`; git
+cannot do it on clone, by design.
 
 A generator reads the header as
 `^(type)(\((scope)\))?(!)?: (subject)( \(#(pr)\))?$` and groups into **Action
diff --git a/tools/init-repo b/tools/init-repo
new file mode 100755
index 00000000..f42e6350
--- /dev/null
+++ b/tools/init-repo
@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Set a clone of this repo up for development.
+
+Everything here is one-time, idempotent and local to the clone: the test
+virtualenv, the git hooks, and the checks that catch the two things that
+otherwise fail confusingly hours later, an old Python and a missing uv.
+
+    tools/init-repo                 the lot, with a report
+    tools/init-repo --hooks-only    just the hooks, silent if already set
+
+Deliberately 3.9-compatible so that on Apple's system Python it reports
+the version problem instead of failing to parse.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+MINIMUM_PYTHON = (3, 11)
+
+OK = "  ✓ "
+WARN = "  ⚠ "
+FAIL = "  ✗ "
+
+
+def say(message: str = "") -> None:
+    """Print in step with the subprocesses this script runs.
+
+    They write straight to the terminal while Python buffers when its
+    output is piped, so without flushing the report arrives after the
+    output of the commands it is describing.
+    """
+    print(message, flush=True)
+
+
+def run(*args, **kwargs):
+    return subprocess.run(args, cwd=str(REPO_ROOT), **kwargs)
+
+
+def enable_hooks(quiet: bool = False) -> bool:
+    """Point git at the repo's hooks, unless a choice was already made.
+
+    Git will not do this on clone, by design: a fresh clone must not be
+    able to run code. An explicit value is never overwritten, so someone
+    who pointed it elsewhere, or nowhere, keeps what they chose.
+    """
+    inside = run("git", "rev-parse", "--git-dir",
+                 capture_output=True, text=True).returncode == 0
+    if not inside:
+        if not quiet:
+            say(f"{WARN}not a git checkout, skipping hooks")
+        return False
+
+    current = run("git", "config", "core.hooksPath",
+                  capture_output=True, text=True).stdout.strip()
+    if current:
+        if not quiet:
+            say(f"{OK}hooks already configured: {current}")
+        return True
+
+    run("git", "config", "core.hooksPath", "hooks")
+    say("  hooks enabled: ruff on staged files, commit subjects checked")
+    return True
+
+
+def check_python() -> bool:
+    version = sys.version_info[:2]
+    if version >= MINIMUM_PYTHON:
+        say(f"{OK}python {version[0]}.{version[1]}")
+        return True
+    say(f"{FAIL}python {version[0]}.{version[1]}, need "
+          f"{MINIMUM_PYTHON[0]}.{MINIMUM_PYTHON[1]}+")
+    say("      Apple's Command Line Tools ship 3.9. Install a newer one:")
+    say("      brew install python")
+    return False
+
+
+def check_uv() -> bool:
+    if shutil.which("uv"):
+        say(f"{OK}uv")
+        return True
+    say(f"{FAIL}uv is missing. It is the only dependency to install by hand:")
+    say("      brew install uv")
+    return False
+
+
+def sync_venv() -> bool:
+    """Create .venv with the test extra, which is what the suite imports."""
+    say("  syncing .venv (uv sync --extra test)...")
+    if run("uv", "sync", "--extra", "test").returncode != 0:
+        say(f"{FAIL}uv sync failed")
+        return False
+    say(f"{OK}.venv ready")
+    return True
+
+
+def install_language_server() -> None:
+    """Optional: the binary the editor LSP points at. `uvx basedpyright`
+    works without it, so a failure here is not worth stopping for."""
+    if run("uv", "tool", "install", "basedpyright",
+           capture_output=True, text=True).returncode == 0:
+        say(f"{OK}basedpyright (language server)")
+    else:
+        say(f"{WARN}basedpyright not installed; `uvx basedpyright` still works")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--hooks-only", action="store_true",
+                        help="Only configure git hooks, quietly")
+    args = parser.parse_args()
+
+    if args.hooks_only:
+        enable_hooks(quiet=True)
+        return 0
+
+    say("\n  Setting up this clone\n")
+    ready = check_python() and check_uv()
+    if not ready:
+        say("\n  Fix the above and run tools/init-repo again.\n")
+        return 1
+
+    ready = sync_venv()
+    enable_hooks()
+    install_language_server()
+
+    say("\n  Next:")
+    say("    make test-unit      the fast suite, before every commit")
+    say("    make typecheck      types across the shipped code")
+    say("    docs/agent/dev.md   how to write code here\n")
+    return 0 if ready else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From fbdb20ebb7b54411a95ac1e7d24a79e90dee5aea Mon Sep 17 00:00:00 2001
From: Arthur <hello@arthware.dev>
Date: Sun, 20 Sep 2026 16:12:08 +0200
Subject: [PATCH 08/11] chore: consolidate the make test targets

Keep one make target per test lane and remove the aliases.

- `make` without a target prints each lane's duration, requirements,
  and whether it uses fixed container names and ports.
- Add `make lint` for the whole tree.
- Recommend `make test-unit` before a push instead of before every
  commit.

Move the details to tests/README.md.
---
 CONTRIBUTING.md   |  2 +-
 Makefile          | 77 +++++++++++++++++++++++++++++++++++------------
 docs/agent/dev.md | 19 ++++++++----
 tests/README.md   | 55 +++++++++++++++++----------------
 tools/init-repo   |  3 +-
 5 files changed, 100 insertions(+), 56 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8f378f23..62948270 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -73,7 +73,7 @@ A bare `make typecheck` reports on `lib`, `stacklets`, `tools` and `hooks`. `tes
 
 ## Tests, style, commits
 
-All three live in [docs/agent/dev.md](docs/agent/dev.md), which is the canonical reference and stays shorter than a duplicate here would. The short version: `make test-unit` before every commit, module tests over unit tests, feature branches only, never push without asking. Commit subjects are the changelog famstack.dev renders, so they follow `<type>(<scope>): <what the product does now>` and every one has to parse.
+All three live in [docs/agent/dev.md](docs/agent/dev.md), which is the canonical reference and stays shorter than a duplicate here would. The short version: the hooks lint every commit for you, `make test-unit` before a push or when a piece of work is done, module tests over unit tests, feature branches only, never push without asking. Commit subjects are the changelog famstack.dev renders, so they follow `<type>(<scope>): <what the product does now>` and every one has to parse.
 
 The hooks check ruff on staged files and the commit subject before a commit exists, rather than in CI. `tools/init-repo` turns them on, as do `make test-unit` and `make typecheck`. To do only that:
 
diff --git a/Makefile b/Makefile
index 322017a3..b17d7eba 100644
--- a/Makefile
+++ b/Makefile
@@ -1,44 +1,81 @@
-# famstack development tasks
+# famstack development tasks.
+#
+# One name per lane. The aliases that used to exist (unit, fast, test,
+# demo, lifecycle, e2e, smoke, test-all, test-integration) are gone: they
+# were eighteen names for six jobs, and `test-all` ran only the lifecycle
+# lane, which is worse than not existing.
+#
+# `make` on its own prints the table.
 
 PYTEST = uv run --extra test pytest
 
+.DEFAULT_GOAL := help
+
+help:
+	@printf '%s\n' \
+	  "" \
+	  "  Linting is automatic: the hooks run ruff on staged files and check" \
+	  "  the commit subject. Nothing to remember per commit." \
+	  "" \
+	  "  Run the cheapest lane that proves what you changed." \
+	  "" \
+	  "  LANE                TIME    NEEDS          EXCLUSIVE  RUN IT WHEN" \
+	  "  make lint           <1s     nothing        no         the whole tree, when you want it" \
+	  "  make test-unit      ~75s    nothing        no         before a push, or when a piece of work is done" \
+	  "  make test-lifecycle ~6m     Docker         yes        lifecycle, env, compose, ports, health" \
+	  "  make test-demo      ~4m     demo instance  yes        it must work against the running bots" \
+	  "  make test-smoke     ?       test-owned rig yes        quick cross-service check" \
+	  "  make test-e2e       20-30m  uninstalled    yes        end of a branch, before review" \
+	  "" \
+	  "  make typecheck              types across the shipped code, not a gate" \
+	  "  make hooks                  point git at the repo's hooks" \
+	  "" \
+	  "  Exclusive means it owns fixed container names and ports, so exactly" \
+	  "  one run at a time on this Mac. ? means nobody has timed it yet;" \
+	  "  if you run one, write the number down. Details: tests/README.md" \
+	  ""
+
+# The whole tree, the way CI runs it. Per commit the hook already covers
+# the staged files, which is faster and is why nothing here is per commit.
+lint: hooks
+	uvx ruff check .
+
 # Type check the shipped code. Not a gate: read what it says about the files
 # you touched. `uvx basedpyright <paths>` narrows it further.
-typecheck types: hooks
+typecheck: hooks
 	-uvx basedpyright
 
 # Point git at the repo's own hooks. Git will not do this on clone, by
 # design: a fresh clone must not be able to run code. The nearest honest
 # thing is to do it the first time someone uses the repo's tooling, which
-# is what every target below depends on.
+# is what the lanes below depend on.
 #
 # Only when unset, so an explicit choice (an absolute path, a different
 # directory, deliberately no hooks) is never overwritten.
 hooks:
 	@tools/init-repo --hooks-only
 
-# Fast unit tests: no Docker. Run before every commit.
-test-unit unit fast test: hooks
+# Offline. No Docker, no live services, nothing shared. Fast enough to run
+# when a piece of work is finished, too slow to run on every commit.
+test-unit: hooks
 	$(PYTEST) tests/framework tests/stacklets -v --ignore=tests/framework/test_config_to_container.py
 
-# Live demo-rig tests: uses the already-running Simpsons demo instance.
-test-demo demo-rig demo:
-	tests/integration/stacktests demo-rig
-
-# Docker lifecycle tests: validates stack up/down/destroy and container env.
-test-lifecycle container-lifecycle lifecycle:
+# Docker lifecycle: up, down, destroy, env rendering, container environment.
+# Owns its own throwaway instance, but on fixed names and ports.
+test-lifecycle:
 	$(PYTEST) tests/framework/test_config_to_container.py -v
 
-# Managed container e2e tests: starts the test rig and runs every e2e test.
-test-e2e container-e2e e2e:
-	tests/integration/stacktests e2e
+# Against the demo instance already running in this checkout. Tests create
+# unique data and clean up after themselves; they never reset the instance.
+test-demo:
+	tests/integration/stacktests demo-rig
 
-# Quick managed-rig e2e subset.
-test-smoke smoke:
+# A small subset of the managed-rig e2e lane, for a quick answer.
+test-smoke:
 	tests/integration/stacktests smoke
 
-# Backwards-compatible names.
-test-all: test-lifecycle
-test-integration: test-e2e
+# The full managed rig: seeds a test-owned instance and runs every e2e test.
+test-e2e:
+	tests/integration/stacktests e2e
 
-.PHONY: hooks typecheck types test-unit unit fast test test-demo demo-rig demo test-lifecycle container-lifecycle lifecycle test-e2e container-e2e e2e test-smoke smoke test-all test-integration
+.PHONY: help hooks lint typecheck test-unit test-lifecycle test-demo test-smoke test-e2e
diff --git a/docs/agent/dev.md b/docs/agent/dev.md
index 74488575..8544eced 100644
--- a/docs/agent/dev.md
+++ b/docs/agent/dev.md
@@ -209,14 +209,21 @@ Keep that file outside the repo. A committed baseline would quietly turn the typ
 Test runner: **`uv run --extra test pytest`**. The `test` extra in `pyproject.toml` declares every dep. Do NOT re-spell with `uvx --with`.
 
 ```bash
-make test-unit       # fast offline framework + stacklet tests
-make test-demo       # live Simpsons demo instance tests
-make test-lifecycle  # Docker lifecycle/container environment tests
-make test-smoke      # quick managed-rig e2e subset
-make test-e2e        # full managed-rig e2e suite
+make                 # the lane table: cost, what each needs, when to run it
+make lint            # <1s, the whole tree. The hook already covers staged files.
+make test-unit       # ~75s, offline, no Docker. Before a push, or when a
+                     #   piece of work is done. Not per commit.
+make test-lifecycle  # ~6m, Docker. Lifecycle, env rendering, compose, health.
+make test-demo       # against the running demo instance.
+make test-smoke      # quick managed-rig e2e subset.
+make test-e2e        # full managed-rig e2e suite.
 ```
 
-Profile details live in [../../tests/README.md](../../tests/README.md).
+Run the cheapest lane that proves what you changed. Every lane but
+`test-unit` owns fixed container names and ports, so exactly one runs at a
+time on a Mac: check nothing else is mid-run first. One name per lane, no
+aliases. Details, and the timings nobody has measured yet, live in
+[../../tests/README.md](../../tests/README.md).
 
 Testing rules:
 
diff --git a/tests/README.md b/tests/README.md
index 542ae74b..2c8fc02a 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -24,16 +24,34 @@ them.
 
 ## Choosing a lane
 
-Use the shortest command that proves the behavior you changed. The profiles
-below are ordered from cheapest to most disruptive.
+Run the cheapest lane that proves what you changed. One name per lane; the
+aliases are gone.
 
-| Profile | Alias | Command | What belongs here |
-|---|---|---|---|
-| `unit` | `fast`, `test` | `make test-unit` | Offline framework and stacklet tests. No Docker daemon, no live services, no production data. |
-| `demo-rig` | `demo` | `make test-demo` | Tests against the already-running Simpsons demo instance in this checkout. Tests must create unique data and clean up after themselves. |
-| `container-lifecycle` | `lifecycle` | `make test-lifecycle` | Docker lifecycle tests for stack orchestration: config rendering, `.env`, `stack up`, `stack down`, `stack destroy`, and container environment behavior. |
-| `container-e2e` | `e2e` | `make test-e2e` | Full managed integration rig tests with real stacklets and Docker. Use this for cross-container behavior and release confidence. |
-| `smoke` | none | `make test-smoke` | Small managed-rig e2e subset for quick checks inside the container e2e lane. |
+Nothing here is per commit. The hooks already run `ruff` on staged files and
+check the commit subject, which costs about a second; a lane that takes a
+minute and a quarter would only teach people to skip it.
+
+| Lane | Time | Needs | Exclusive | Run it when |
+|---|---|---|---|---|
+| `make lint` | <1s | nothing | no | The whole tree, when you want more than the staged files the hook checks. What CI runs. |
+| `make test-unit` | ~75s | nothing | no | Before a push, or when a coherent piece of work is done. Offline framework and stacklet tests: no Docker, no live services, no production data. |
+| `make test-lifecycle` | ~6m | Docker | yes | You changed lifecycle, config rendering, `.env`, compose, container names, ports, volumes or health wiring. Owns a throwaway instance on fixed names. |
+| `make test-demo` | ~4m | the demo instance running | yes | The behaviour has to work against the already-running bots and real service wiring. Tests create unique data and clean up after themselves; they never reset the instance. |
+| `make test-smoke` | ? | a test-owned rig | yes | A quick answer on a cross-service path. Seeds secrets and brings the required stacklets up first, so it is not read-only. |
+| `make test-e2e` | 20-30m | an uninstalled instance | yes | End of a branch, or before asking for review, when the change crosses container boundaries. Uninstall first: it seeds and owns the instance it runs against. |
+
+**Exclusive** means the lane owns fixed container names and ports, so exactly
+one run at a time on this Mac. Check nothing else is mid-run before starting
+one, and see [RFC-003](../docs/adr/rfc-003-agentic-development-harness.md) for
+why that is courtesy rather than enforcement today.
+
+**?** means nobody has timed it. If you run one, put the number here.
+
+`make` on its own prints a short version of this table.
+
+Do not run managed integration cleanup or reset commands against a production
+instance. `stacktests` guards this with a test-instance sentinel, but
+destructive test-rig commands still require care.
 
 ## Structure
 
@@ -58,22 +76,3 @@ starts required stacklets, and keeps the rig reusable between runs.
 `tests/integration/eval/` is opt-in prompt and model evaluation. It is excluded
 from normal pytest collection and is run with `tests/integration/stacktests eval`.
 
-## Choosing A Profile
-
-Run `make test-unit` while coding. It is the default pre-commit check.
-
-Run `make test-demo` when the behavior must work in the already-running demo
-instance and the test can be written to clean up after itself.
-
-Run `make test-lifecycle` when changing framework lifecycle, compose generation,
-environment rendering, container names, ports, volumes, or health wiring.
-
-Run `make test-smoke` for a quick managed-rig e2e check after changing a
-cross-service path.
-
-Run `make test-e2e` at the end of a branch or before asking for review when the
-change crosses container boundaries.
-
-Do not run managed integration cleanup/reset commands against a production
-instance. `stacktests` guards this with a test-instance sentinel, but destructive
-test-rig commands still require care.
diff --git a/tools/init-repo b/tools/init-repo
index f42e6350..9fb591a2 100755
--- a/tools/init-repo
+++ b/tools/init-repo
@@ -130,7 +130,8 @@ def main() -> int:
     install_language_server()
 
     say("\n  Next:")
-    say("    make test-unit      the fast suite, before every commit")
+    say("    make                the test lanes, what each costs, when to run it")
+    say("    make test-unit      the fast suite, before a push")
     say("    make typecheck      types across the shipped code")
     say("    docs/agent/dev.md   how to write code here\n")
     return 0 if ready else 1

From 3f711aeea148397983358c6c5dba17178593b36c Mon Sep 17 00:00:00 2001
From: Arthur <hello@arthware.dev>
Date: Sun, 20 Sep 2026 16:35:53 +0200
Subject: [PATCH 09/11] fix(doctor): compare container env with the compose
 config

`stack doctor` compared a container's environment with the stacklet's
rendered `.env`. Services that set a different value in their compose
file, such as a container path or an internal hostname, were reported
as drifted after every recreate.

Compare with the environment that `docker compose config` resolves for
the service. This also removes the special cases for image defaults and
for variables a service does not receive.
---
 lib/stack/cli.py               |  13 +++-
 lib/stack/docker.py            |  37 ++++++-----
 lib/stack/doctor.py            |  75 +++++++++------------
 tests/framework/test_doctor.py | 118 ++++++++++++++++-----------------
 4 files changed, 120 insertions(+), 123 deletions(-)

diff --git a/lib/stack/cli.py b/lib/stack/cli.py
index 669424f3..c9930671 100644
--- a/lib/stack/cli.py
+++ b/lib/stack/cli.py
@@ -902,12 +902,21 @@ def missing_secrets(stacklet_id):
         required = manifests.get(stacklet_id, {}).get("required_secrets", [])
         return [name for name in required if not stck.secret(stacklet_id, name)]
 
+    # What compose would give each service now, keyed by container name.
+    # Comparing a container against this, rather than against the
+    # stacklet's rendered env, is what keeps a deliberate compose
+    # override from reading as drift forever.
+    expected = {}
+    for s in discovered:
+        compose_file = docker.find_compose_file(Path(s["path"]))
+        if compose_file:
+            expected.update(docker.compose_service_env(compose_file))
+
     findings = doctor.diagnose(
         stacklets,
-        stck.env,
+        lambda container: expected.get(container, {}),
         docker.containers_for,
         docker.container_env,
-        docker.image_env,
         missing_secrets=missing_secrets,
         stale=stck.list().get("stale", []),
     )
diff --git a/lib/stack/docker.py b/lib/stack/docker.py
index b1bf9eed..5670e537 100644
--- a/lib/stack/docker.py
+++ b/lib/stack/docker.py
@@ -366,33 +366,36 @@ def container_env(name: str) -> dict:
         return {}
 
 
-def image_env(name: str) -> dict:
-    """The environment baked into the image a container was started from.
+def compose_service_env(compose_file: str | Path) -> dict[str, dict[str, str]]:
+    """What compose would give each service, resolved the way it resolves it.
 
-    `container_env` returns the image's defaults *plus* whatever compose
-    passed in, and the two are indistinguishable once the container exists.
-    Reading the image separately is what lets a caller tell them apart, so
-    an image author's own setting is never mistaken for our config drifting.
+    `docker compose config` applies the project's `.env`, each service's
+    `env_file` and its `environment:` block, with interpolation, and
+    reports the result. That is the only honest thing to compare a running
+    container against, because it is literally what a fresh container
+    would receive.
+
+    An unreadable compose file returns nothing, and the caller reports no
+    drift rather than guessing at one.
     """
     try:
         r = _docker(
-            "inspect", name, "--format", "{{.Config.Image}}",
-            capture_output=True, text=True, timeout=10,
-        )
-        image = r.stdout.strip() if r.returncode == 0 else ""
-        if not image:
-            return {}
-        r = _docker(
-            "inspect", image, "--format",
-            "{{range .Config.Env}}{{println .}}{{end}}",
-            capture_output=True, text=True, timeout=10,
+            "compose", "-f", str(compose_file), "config", "--format", "json",
+            capture_output=True, text=True, timeout=60,
         )
         if r.returncode != 0:
             return {}
-        return _parse_env(r.stdout)
+        parsed = json.loads(r.stdout)
     except Exception:
         return {}
 
+    services = parsed.get("services") or {}
+    return {
+        name: {k: "" if v is None else str(v)
+               for k, v in (service.get("environment") or {}).items()}
+        for name, service in services.items()
+    }
+
 
 def running_project_ids() -> set[str]:
     """Convenience wrapper — stacklet IDs with running containers."""
diff --git a/lib/stack/doctor.py b/lib/stack/doctor.py
index 17646bc6..9e7fa796 100644
--- a/lib/stack/doctor.py
+++ b/lib/stack/doctor.py
@@ -50,49 +50,38 @@ def is_error(self) -> bool:
         return self.level == ERROR
 
 
-def env_drift(rendered: dict, actual: dict, ignore: frozenset = _RUNTIME_KEYS) -> list[str]:
-    """Config keys whose live value no longer matches what stack.toml renders.
+def env_drift(expected: dict, actual: dict, ignore: frozenset = _RUNTIME_KEYS) -> list[str]:
+    """Config keys whose live value is not what compose would set today.
+
+    `expected` is what `docker compose config` resolves for that service:
+    its `env_file` and its `environment:` block, interpolated. That is the
+    only honest expectation, because it is literally what a fresh
+    container would receive.
+
+    Comparing against the stacklet's rendered env instead produced false
+    positives that no `stack up` could ever clear, in three flavours. The
+    rendered env is the whole set for the project, so every variable a
+    service was never given looked missing, and watchtower appeared to
+    have 36 problems. An image's own defaults are not ours to change, so
+    gotenberg reported a TZ error whose suggested fix provably did
+    nothing. And a compose file that deliberately overrides a value, a
+    container path where the host has a host path, a service name where
+    the host has a LAN URL, reported that override as drift forever.
 
     Returns key names only, never values - this environment carries admin
-    passwords, API tokens, and database credentials, and a diagnostic that
+    passwords, API tokens and database credentials, and a diagnostic that
     prints them turns a config warning into a credential leak in whatever
     log or issue tracker the output gets pasted into.
-
-    Only keys the container actually carries are compared. A stacklet's
-    rendered env is the whole set for the compose project, while each
-    service receives its own subset - so "missing" overwhelmingly means
-    "this service was never given that variable", not "config drifted".
-    Reporting those made watchtower look like it had 36 problems and
-    buried the one setting that had genuinely changed.
     """
     drifted = []
-    for key, expected in rendered.items():
+    for key, value in expected.items():
         if key in ignore or key not in actual:
             continue
-        if actual[key] != str(expected):
+        if actual[key] != str(value):
             drifted.append(key)
     return sorted(drifted)
 
 
-def compose_supplied(actual: dict, baked: dict) -> dict:
-    """The part of a container's environment that compose actually set.
-
-    A container's environment is the image's own defaults plus whatever
-    compose passed in. Only the second half can drift from stack.toml; the
-    first half belongs to the image author and no famstack command can
-    change it. Comparing it produces a finding that is permanently true and
-    whose suggested fix provably does nothing, which is how gotenberg came
-    to report a TZ error that survived every `stack up docs`.
-
-    A value equal to the image's default is treated as not-ours. That is
-    deliberately conservative: if compose sets a key to exactly what the
-    image already baked, real drift on that key goes unreported. Missing a
-    finding costs one debugging session; a permanent false positive teaches
-    the reader to skim past every finding, including the true ones.
-    """
-    return {k: v for k, v in actual.items() if baked.get(k) != v}
-
-
 def check_env_drift(stacklet: str, container: str, drifted: list[str]) -> Finding | None:
     """A running container carrying superseded config."""
     if not drifted:
@@ -197,22 +186,22 @@ def check_endpoint(name: str, url: str, reachable: bool) -> Finding | None:
     )
 
 
-def diagnose(stacklets, rendered_env, containers_for, container_env,
-             image_env, *, missing_secrets=None, stale=()) -> list[Finding]:
+def diagnose(stacklets, expected_env, containers_for, container_env,
+             *, missing_secrets=None, stale=()) -> list[Finding]:
     """Run every check across the given stacklets.
 
     The collaborators are injected rather than imported so the whole walk
     is testable with plain dicts - no Docker, no instance. Each is a
     callable taking a stacklet id (or container name) and returning facts.
+    `expected_env` takes a *container* name and returns what compose would
+    give that service now; an empty answer means the question could not be
+    asked, and no drift is reported rather than a guess.
     `missing_secrets` is optional so a caller that has no secret store to
     consult still gets the container checks. `stale` names the stacklets
     whose containers predate the code on disk, which only a caller with a
     git checkout can work out.
 
-    A stacklet whose env cannot be rendered is skipped rather than fatal:
-    one misconfigured stacklet should not stop the others being diagnosed,
-    which is the moment a doctor is most needed.
-    """
+"""
     findings: list[Finding] = []
     for stacklet in stacklets:
         containers = containers_for(stacklet)
@@ -229,11 +218,6 @@ def diagnose(stacklets, rendered_env, containers_for, container_env,
             if found:
                 findings.append(found)
 
-        try:
-            rendered = rendered_env(stacklet)
-        except Exception:
-            rendered = None
-
         for container in containers:
             name = container["name"]
             if container["state"] != "running":
@@ -242,9 +226,10 @@ def diagnose(stacklets, rendered_env, containers_for, container_env,
                     findings.append(found)
                 # A stopped container's environment says nothing useful.
                 continue
-            if rendered:
-                ours = compose_supplied(container_env(name), image_env(name))
-                drifted = env_drift(rendered, ours)
+
+            expected = expected_env(name)
+            if expected:
+                drifted = env_drift(expected, container_env(name))
                 found = check_env_drift(stacklet, name, drifted)
                 if found:
                     findings.append(found)
diff --git a/tests/framework/test_doctor.py b/tests/framework/test_doctor.py
index 3008db97..4d0ac639 100644
--- a/tests/framework/test_doctor.py
+++ b/tests/framework/test_doctor.py
@@ -14,7 +14,6 @@
     check_exited,
     check_missing_secrets,
     check_stale_code,
-    compose_supplied,
     diagnose,
     env_drift,
     summarise,
@@ -37,10 +36,9 @@ def _fixture_instance():
     }
     return (
         ["core"],
-        lambda s: {"MATRIX_SERVER_NAME": "simpson"},
+        lambda container: {"MATRIX_SERVER_NAME": "simpson"},
         lambda s: containers.get(s, []),
         lambda n: envs.get(n, {}),
-        lambda n: {},
     )
 
 
@@ -69,11 +67,10 @@ def test_is_a_warning_not_an_error(self):
     def test_diagnose_raises_one_per_stale_stacklet(self):
         findings = diagnose(
             ["docs", "photos"],
-            lambda s: {},
+            lambda container: {},
             lambda s: [{"name": f"stack-{s}", "state": "running",
                         "exit_code": 0, "since": ""}],
             lambda n: {},
-            lambda n: {},
             stale=["docs"],
         )
 
@@ -136,56 +133,70 @@ def test_drift_never_leaks_values():
     assert "ADMIN_PASSWORD" in rendered_text  # the name is the useful part
 
 
-# ── compose_supplied ─────────────────────────────────────────────────────
+# ── what a container is compared against ─────────────────────────────────
+#
+# Every case here is a false positive doctor actually reported, and each
+# one survived `stack up` because nothing about the container was wrong.
 
-def test_image_baked_value_is_not_ours_to_fix():
-    # The gotenberg case, with its real values. `gotenberg/gotenberg:8` bakes
-    # TZ=UTC; stack.toml says Europe/Berlin; the compose file never passes TZ
-    # to that service. Doctor reported drift on every run and told the reader
-    # to run `stack up docs`, which recreated the container and changed
-    # nothing, because there was nothing to change.
-    actual = {"TZ": "UTC", "PAPERLESS_URL": "http://localhost:42020"}
-    baked = {"TZ": "UTC"}
-    assert compose_supplied(actual, baked) == {"PAPERLESS_URL": "http://localhost:42020"}
+def _running(name):
+    return [{"name": name, "state": "running", "exit_code": 0, "since": "Up 4 minutes"}]
 
 
-def test_compose_overriding_an_image_default_is_still_ours():
-    # Same key, different value: compose won, so we own it and it can drift.
-    assert compose_supplied({"TZ": "Europe/Berlin"}, {"TZ": "UTC"}) == {"TZ": "Europe/Berlin"}
+def test_a_variable_compose_never_passes_is_not_drift():
+    """The gotenberg case. `gotenberg:8` bakes TZ=UTC, stack.toml says
+    Europe/Berlin, and the compose file never passes TZ to that service.
+    Doctor reported drift on every run and told the reader to run
+    `stack up docs`, which changed nothing because nothing was wrong."""
+    findings = diagnose(
+        ["docs"],
+        lambda container: {},           # compose sets nothing for this service
+        lambda s: _running("stack-docs-gotenberg"),
+        lambda n: {"TZ": "UTC"},        # the image's own default
+    )
+    assert findings == []
 
 
-def test_gotenberg_style_container_produces_no_finding():
-    # End to end through the caller's entry point, which is where the bug was
-    # visible. This is the regression guard: it fails if the walk ever goes
-    # back to comparing a container's whole environment.
-    containers = [{"name": "stack-docs-gotenberg", "state": "running",
-                   "exit_code": 0, "since": "Up 4 minutes"}]
+def test_a_deliberate_compose_override_is_not_drift():
+    """The curator case. The compose file sets the *container* path while
+    the stacklet renders the host path, and the service name while the
+    host renders a LAN URL. Compared against the rendered env those read
+    as drift forever, through any number of recreates."""
     findings = diagnose(
-        ["docs"],
-        lambda s: {"TZ": "Europe/Berlin"},      # what stack.toml renders
-        lambda s: containers,
-        lambda n: {"TZ": "UTC"},                # container, from the image
-        lambda n: {"TZ": "UTC"},                # image's own default
+        ["memory"],
+        lambda container: {"BRAIN_REPO_DIR": "/data/memory/brain",
+                           "CODE_URL": "http://stack-code:3000"},
+        lambda s: _running("stack-memory-curator"),
+        lambda n: {"BRAIN_REPO_DIR": "/data/memory/brain",
+                   "CODE_URL": "http://stack-code:3000"},
     )
     assert findings == []
 
 
-def test_real_drift_still_reported_when_the_image_is_silent():
-    # The guard must not swallow the incident it was built for: the image
-    # says nothing about the realm, so a stale value is genuinely ours.
-    containers = [{"name": "stack-core-bot-runner", "state": "running",
-                   "exit_code": 0, "since": "Up 4 minutes"}]
+def test_real_drift_is_still_reported():
+    """The guard must not swallow the incident it exists for: the
+    container was created before the value changed."""
     findings = diagnose(
         ["core"],
-        lambda s: {"MATRIX_SERVER_NAME": "simpson"},
-        lambda s: containers,
+        lambda container: {"MATRIX_SERVER_NAME": "simpson"},
+        lambda s: _running("stack-core-bot-runner"),
         lambda n: {"MATRIX_SERVER_NAME": "test.local"},
-        lambda n: {},
     )
     assert len(findings) == 1
     assert "superseded config" in findings[0].title
 
 
+def test_an_unanswerable_question_reports_nothing():
+    """An unreadable compose file means we cannot say what the container
+    should have. Silence beats a guess."""
+    findings = diagnose(
+        ["docs"],
+        lambda container: {},
+        lambda s: _running("stack-docs-paperless"),
+        lambda n: {"ANYTHING": "at all"},
+    )
+    assert findings == []
+
+
 # ── findings ─────────────────────────────────────────────────────────────
 
 def test_env_drift_finding_is_actionable():
@@ -245,8 +256,8 @@ def test_a_stacklet_that_declares_no_secrets_is_never_flagged():
     containers = [{"name": "stack-x-1", "state": "running",
                    "exit_code": 0, "since": "Up 1 minute"}]
     findings = diagnose(
-        ["x"], lambda s: {"A": "1"}, lambda s: containers, lambda n: {"A": "1"},
-        lambda n: {}, missing_secrets=lambda s: [],
+        ["x"], lambda container: {"A": "1"}, lambda s: containers,
+        lambda n: {"A": "1"}, missing_secrets=lambda s: [],
     )
     assert findings == []
 
@@ -257,8 +268,8 @@ def test_diagnose_finds_the_missing_vault_token():
     containers = [{"name": "stack-memory-wiki", "state": "running",
                    "exit_code": 0, "since": "Up 2 days"}]
     findings = diagnose(
-        ["memory"], lambda s: {}, lambda s: containers, lambda n: {},
-        lambda n: {}, missing_secrets=lambda s: ["MEMORY_BOT_TOKEN"],
+        ["memory"], lambda container: {}, lambda s: containers, lambda n: {},
+        missing_secrets=lambda s: ["MEMORY_BOT_TOKEN"],
     )
     assert len(findings) == 1
     assert findings[0].fix == "stack setup memory"
@@ -269,7 +280,7 @@ def test_a_stacklet_that_was_never_installed_is_not_flagged():
     # credentials are supposed to be absent, and telling the reader to set
     # up something they never asked for is noise.
     findings = diagnose(
-        ["memory"], lambda s: {}, lambda s: [], lambda n: {}, lambda n: {},
+        ["memory"], lambda container: {}, lambda s: [], lambda n: {},
         missing_secrets=lambda s: ["MEMORY_BOT_TOKEN"],
     )
     assert findings == []
@@ -307,35 +318,24 @@ def test_diagnose_skips_env_check_for_stopped_containers():
     containers = [{"name": "stack-x-dead", "state": "exited",
                    "exit_code": 1, "since": "1 hour ago"}]
     findings = diagnose(
-        ["x"], lambda s: {"A": "new"}, lambda s: containers, lambda n: {"A": "old"},
-        lambda n: {},
+        ["x"], lambda container: {"A": "new"}, lambda s: containers,
+        lambda n: {"A": "old"},
     )
     assert len(findings) == 1
     assert "exited" in findings[0].title
 
 
-def test_diagnose_survives_a_stacklet_that_cannot_render():
-    # One broken config must not stop the rest being diagnosed.
-    def exploding_env(stacklet):
-        raise ValueError("bad config")
-
-    containers = [{"name": "stack-x-1", "state": "running",
-                   "exit_code": 0, "since": "Up 1 minute"}]
-    assert diagnose(["x"], exploding_env, lambda s: containers,
-                    lambda n: {}, lambda n: {}) == []
-
-
 def test_diagnose_ignores_stacklets_with_no_containers():
-    assert diagnose(["absent"], lambda s: {"A": "1"}, lambda s: [],
-                    lambda n: {}, lambda n: {}) == []
+    assert diagnose(["absent"], lambda container: {"A": "1"}, lambda s: [],
+                    lambda n: {}) == []
 
 
 def test_healthy_instance_yields_nothing():
     containers = [{"name": "stack-x-1", "state": "running",
                    "exit_code": 0, "since": "Up 1 minute"}]
     findings = diagnose(
-        ["x"], lambda s: {"A": "1"}, lambda s: containers, lambda n: {"A": "1"},
-        lambda n: {},
+        ["x"], lambda container: {"A": "1"}, lambda s: containers,
+        lambda n: {"A": "1"},
     )
     assert findings == []
     assert summarise(findings) == "No problems found."

From 88d4936362bb5a37b06b2be4611e0f10d206e17d Mon Sep 17 00:00:00 2001
From: Arthur <hello@arthware.dev>
Date: Sun, 20 Sep 2026 16:56:16 +0200
Subject: [PATCH 10/11] feat(cli): show the actual checkout version in all
 commands

Derive the version from `git describe --tags --dirty` instead of the
`VERSION` constant, for example `0.3.0-beta.3-104-g9a5bdc9-dirty`.
`version`, `status`, `list`, `doctor` and `update` print the same value.

- `stack doctor` prints the version and warns when a newer release tag
  exists locally. It does not fetch.
- `stack update` prints the current version first, and shows how many
  commits the checkout is ahead of the newest release.

The release gate still uses `VERSION`. If it differs from the tag, both
values are shown.
---
 docs/admin-guide.md                           | 11 ++++
 ...-002-installation-instances-and-updates.md | 17 +++---
 docs/agent/ops.md                             |  2 +-
 lib/stack/cli.py                              | 61 ++++++++++++++++---
 lib/stack/doctor.py                           | 25 ++++++++
 lib/stack/stack.py                            |  8 ++-
 lib/stack/updater.py                          | 39 +++++++++++-
 tests/framework/test_doctor.py                | 38 ++++++++++++
 tests/framework/test_updater.py               | 47 +++++++++++++-
 9 files changed, 226 insertions(+), 22 deletions(-)

diff --git a/docs/admin-guide.md b/docs/admin-guide.md
index 4270e49c..ca96f056 100644
--- a/docs/admin-guide.md
+++ b/docs/admin-guide.md
@@ -852,6 +852,17 @@ It does not restart anything. New code on disk is not new code running: a stackl
 ./stack update --yes             # skip the confirmation
 ```
 
+Every form fetches tags first, including `--dry-run`: without it the answer
+would only be as fresh as your last fetch. It opens with the version and,
+once it knows, the move it is proposing:
+
+```
+  famstack 0.3.0-beta.3
+  Fetching releases...
+
+  Update  v0.3.0-beta.3 → v0.3.0-beta.4
+```
+
 A stacklet is named only if the release changed files inside it and it is running, so a documentation release asks for nothing. If the release changed anything under `lib/`, every running stacklet is named, because that is the code they all share.
 
 ### Updating by hand
diff --git a/docs/adr/rfc-002-installation-instances-and-updates.md b/docs/adr/rfc-002-installation-instances-and-updates.md
index 8a3167bb..5e1822ea 100644
--- a/docs/adr/rfc-002-installation-instances-and-updates.md
+++ b/docs/adr/rfc-002-installation-instances-and-updates.md
@@ -37,11 +37,11 @@ which detaches HEAD, after which `git pull` no longer does what the admin
 guide says it does. There is no `stack update`. Five tags exist and nothing in
 the product knows about them.
 
-**P2. The version string is a constant in the working tree.**
-`VERSION = "0.3.0-beta.3"` (`lib/stack/cli.py:197`) is what `stack version`
-and `stack status` report, next to a short SHA. On a `main` checkout between
-tags that number is simply the last one someone typed, so it names a hundred
-different trees.
+**P2. The version string was a constant in the working tree.** *(fixed)*
+`VERSION = "0.3.0-beta.3"` was what `stack version` and `stack status`
+reported, so on a checkout between tags it named a hundred different trees.
+Every surface now derives it from `git describe --tags --dirty`, which
+answers by comparing the tree against the commit a tag points at.
 
 **P3. A release does not describe what runs.** Across the stacklets there are
 19 image references. Exactly one is pinned to an exact upstream version
@@ -190,8 +190,11 @@ Each phase stands alone and ships on its own. Gates are what proves it.
   out, restart stacklets whose files changed, run doctor.~~ Shipped. It
   refuses to restart anything when the stash conflicts, and prints the
   recovery commands instead.
-- `stack version` reports the checkout's tag, the SHA, and whether the tree is
-  dirty or behind. *(open: the version is still a constant in the tree)*
+- ~~`stack version` reports the checkout's tag, the SHA, and whether the tree
+  is dirty.~~ Shipped. `git describe --tags --dirty` compares the tree against
+  the commit a tag points at, and every surface prints the same derived
+  string. The constant stays in `cli.py` for the release gate to check
+  against the tag; it is no longer what anyone is shown.
 - ~~Delete `./stack updates` from ops.md or implement it.~~ Done: the row is
   removed and the manual procedure is documented, which is what `stack update`
   has to automate.
diff --git a/docs/agent/ops.md b/docs/agent/ops.md
index a0bc5065..c3d20237 100644
--- a/docs/agent/ops.md
+++ b/docs/agent/ops.md
@@ -120,7 +120,7 @@ A release is a git tag. `./stack update` moves the checkout to one and names wha
 - **Before v0.3.0-beta.4 there is no `update`.** By hand: `git fetch --tags && git checkout <tag> && ./stack doctor`, then restart what `git diff --name-only <old> <new> -- stacklets/` names.
 - **Works from a branch or a fork.** On `main` it moves to the tag and says the branch is left behind (`git switch main` returns). Tags are fetched from every remote, so a fork needs the project added as a remote or there is nothing to update to.
 - **A tag checkout is a detached HEAD.** `git pull` fails there. Never suggest `git pull origin main` as the fix: it succeeds and silently moves the instance onto unreleased code while `./stack version` still reports the last release.
-- **`./stack version` is a constant in the tree,** not the running state. `git describe --tags` is the truth.
+- **`./stack version` now says what is running,** not what the source constant claims: `0.3.0-beta.3-104-g9a5bdc9-dirty` is the tag, the distance past it, the commit, and an unclean tree. `version`, `status`, `list`, `doctor` and `update` all print the same string. `./stack doctor` adds a warning when a newer release exists, without fetching, so that half is as fresh as the last `git fetch`.
 - **The instance survives a tag switch.** Config, secrets, data and `~/<product>-extensions/` are all outside git.
 
 Full prose: [../admin-guide.md](../admin-guide.md) § Updating.
diff --git a/lib/stack/cli.py b/lib/stack/cli.py
index c9930671..b15c096f 100644
--- a/lib/stack/cli.py
+++ b/lib/stack/cli.py
@@ -628,6 +628,18 @@ def print_up_success(result: dict, stck: Stack) -> None:
     print()
 
 
+def running_version_of(stck) -> str:
+    """The version to show a human: the tag, plus how far past it we are.
+
+    Every surface that prints a version goes through here, so `version`,
+    `doctor`, `update` and `list` cannot disagree about what is running.
+    """
+    from .updater import Checkout, running_version
+
+    checkout = Checkout(stck.root)
+    return running_version(checkout.describe() if checkout.is_git() else "", VERSION)
+
+
 def _short_path(path) -> str:
     """Home-relative path for display."""
     home = str(Path.home())
@@ -668,8 +680,7 @@ def print_list(result: dict, stck=None) -> None:
     shipped, extensions = _split_by_origin(stacklets)
     status_list(shipped)
     print_extensions_section(extensions, result.get("extension_dirs", []))
-    sha = stck._git_commit() if stck else ""
-    version_info = f"  {DIM}{VERSION} ({sha}){RESET}" if sha else ""
+    version_info = f"  {DIM}{running_version_of(stck)}{RESET}" if stck else ""
     print(f"  {result.get('online', 0)}/{result.get('total', 0)} online{version_info}")
     stale = result.get("stale", [])
     if stale:
@@ -698,7 +709,10 @@ def print_status(result: dict) -> None:
 
     col = 14
     print()
-    print(f"  {ORANGE}{BOLD}{name}{RESET} {DIM}{version} ({commit}){RESET}")
+    # The version already carries the commit when the checkout is past a
+    # tag, so repeating it would read as two different answers.
+    suffix = "" if commit and commit in version else f" ({commit})"
+    print(f"  {ORANGE}{BOLD}{name}{RESET} {DIM}{version}{suffix}{RESET}")
     print()
 
     print(f"  {BOLD}System{RESET}")
@@ -921,7 +935,23 @@ def missing_secrets(stacklet_id):
         stale=stck.list().get("stale", []),
     )
 
+    # What this instance is running, and whether a release has passed it.
+    # No fetch: doctor is run often, and often when something is
+    # unreachable, so it answers from the tags this clone already has.
+    from .updater import Checkout, latest_tag
+
+    checkout = Checkout(stck.root)
+    position = checkout.describe() if checkout.is_git() else ""
+    latest = latest_tag(checkout.tags()) if position else ""
+    release = doctor.check_release(
+        position, latest, up_to_date=bool(latest) and checkout.contains(latest))
+    if release:
+        findings.insert(0, release)
+
     print()
+    if position:
+        print(f"  {ORANGE}{BOLD}{stck.product_name()}{RESET} "
+              f"{DIM}{running_version_of(stck)}{RESET}\n")
     if not findings:
         print(f"  {GREEN}✓{RESET}  {doctor.summarise(findings)}\n")
         return
@@ -1368,7 +1398,14 @@ def handle_update(stck, args):
                      "hint": "git clone https://github.com/famstack-dev/famstack.git"})
         sys.exit(1)
 
-    print("\n  Fetching releases...", file=sys.stderr)
+    # The same line doctor opens with, so both commands answer "what am I
+    # running" identically. The positions themselves are in the plan below.
+    # flush: the progress lines below go to stderr unbuffered, and this
+    # one would otherwise arrive after them whenever output is piped.
+    print(f"\n  {ORANGE}{BOLD}{stck.product_name()}{RESET} "
+          f"{DIM}{running_version_of(stck)}{RESET}", flush=True)
+
+    print("  Fetching releases...", file=sys.stderr)
     fetched, fetch_err = checkout.fetch_tags()
     if not fetched:
         print(f"  {ORANGE}\u26a0{RESET}  Could not reach the remote. Working from the tags already here.",
@@ -1403,9 +1440,12 @@ def handle_update(stck, args):
     # and stash whatever is in progress to do it.
     branch = checkout.branch()
     if not args.tag and checkout.contains(target):
-        where = f"{branch}, which is development," if branch else checkout.describe()
-        print(f"\n  {GREEN}\u2713{RESET}  {TEAL}{where}{RESET} "
-              f"is already past {target}, the newest release.")
+        ahead = checkout.commits_ahead_of(target)
+        distance = f"{ahead} commit" + ("s" if ahead != 1 else "")
+        print(f"\n  {GREEN}\u2713{RESET}  Your checkout is {TEAL}{distance} "
+              f"ahead{RESET} of {target}, the newest release.")
+        if branch:
+            print(f"  {DIM}You are on {branch}, which is development.{RESET}")
         print(f"  {DIM}To move onto that release anyway: "
               f"stack update {target}{RESET}")
         if len(checkout.remotes()) > 1:
@@ -1566,8 +1606,7 @@ def _restore_edits(checkout, was, target, collisions) -> bool:
 
 
 def handle_version(stck, args):
-    sha = stck._git_commit()
-    print(f"{stck.product_name()} {VERSION} ({sha})")
+    print(f"{stck.product_name()} {running_version_of(stck)}")
 
 
 # ── Plugin loader ─────────────────────────────────────────────────────────
@@ -1753,7 +1792,9 @@ def main():
     p = sub.add_parser("update")
     p.add_argument("tag", nargs="?", default=None,
                    help="Release to move to (default: the newest)")
-    p.add_argument("--dry-run", action="store_true", help="Show what would change")
+    p.add_argument("--dry-run", action="store_true",
+                   help="Show the plan and stop. Still fetches tags, "
+                        "or the answer would be as stale as your last fetch")
     p.add_argument("--yes", action="store_true", help="Skip the confirmation")
     p = sub.add_parser("setup"); p.add_argument("stacklet")
     p = sub.add_parser("env"); p.add_argument("stacklet")
diff --git a/lib/stack/doctor.py b/lib/stack/doctor.py
index 9e7fa796..a3547c5b 100644
--- a/lib/stack/doctor.py
+++ b/lib/stack/doctor.py
@@ -169,6 +169,31 @@ def check_stale_code(stacklet: str) -> Finding:
     )
 
 
+def check_release(position: str, latest: str, up_to_date: bool) -> Finding | None:
+    """Whether a newer release exists than the one this checkout is on.
+
+    Read from the tags this clone already has, because doctor does not
+    reach the network: it is run often, and often on an instance whose
+    problem is that something is unreachable. So the answer is only as
+    fresh as the last fetch, and the detail says so rather than implying
+    authority it does not have.
+
+    A warning, not an error. Being a release behind breaks nothing, and
+    doctor's exit code gates scripts.
+    """
+    if not latest or up_to_date:
+        return None
+    return Finding(
+        level=WARN,
+        title=f"a newer release is available: {latest}",
+        detail=(
+            f"This checkout is at {position}. Tags are read from this clone, "
+            f"so the newest release may be newer still."
+        ),
+        fix="stack update",
+    )
+
+
 def check_endpoint(name: str, url: str, reachable: bool) -> Finding | None:
     """A configured endpoint that does not answer.
 
diff --git a/lib/stack/stack.py b/lib/stack/stack.py
index 3bf27751..5759d861 100644
--- a/lib/stack/stack.py
+++ b/lib/stack/stack.py
@@ -655,10 +655,16 @@ def changes_since(commit: str) -> list[str]:
     def status(self) -> dict:
         """Full system status: version, runtime, host, stacklets."""
         from .cli import VERSION
+        from .updater import Checkout, running_version
 
+        checkout = Checkout(self.root)
         info = {
             "name": self.product_name(),
-            "version": VERSION,
+            # What is running, not the constant in the source: the tag,
+            # plus how far past it this checkout sits.
+            "version": running_version(
+                checkout.describe() if checkout.is_git() else "", VERSION),
+            "release": VERSION,
             "commit": self._git_commit(),
             "python": platform.python_version(),
             "os": platform.system(),
diff --git a/lib/stack/updater.py b/lib/stack/updater.py
index b425a06a..aa0d8857 100644
--- a/lib/stack/updater.py
+++ b/lib/stack/updater.py
@@ -63,6 +63,31 @@ def latest_tag(tags) -> str | None:
     return max(releases, key=version_key) if releases else None
 
 
+def running_version(describe: str, constant: str) -> str:
+    """What this checkout is, rather than what the source says it is.
+
+    `VERSION` in `lib/stack/cli.py` is the last number a human typed, and
+    between tags it names every tree since: a checkout 102 commits past
+    beta.3 still calls itself beta.3. `git describe --tags --dirty`
+    answers exactly the right question, comparing the working tree
+    against the commit a tag points at, so the distance, the commit and
+    an unclean tree all come out in one string.
+
+    Three cases. Sitting on the tag, the tag is the whole answer. Past
+    it, git's own string is. And in the window where the release gate has
+    bumped the constant but not yet tagged, the two disagree and both are
+    reported, because hiding either one is a lie.
+    """
+    if not describe:
+        return constant
+    position = describe.lstrip("v")
+    if position == constant:
+        return constant
+    if position.startswith(constant):
+        return position
+    return f"{constant} (checkout at {describe})"
+
+
 # ── What a jump makes stale ──────────────────────────────────────────────
 
 def _is_framework(path: str) -> bool:
@@ -156,10 +181,20 @@ def current_tag(self) -> str | None:
         return out if code == 0 else None
 
     def describe(self) -> str:
-        """Human position: a tag, a tag plus commits, or a bare SHA."""
-        code, out, _ = self._run("describe", "--tags", "--always")
+        """Human position: a tag, a tag plus commits, or a bare SHA.
+
+        `--dirty` because uncommitted work is part of the answer: a tree
+        one edit away from a tag is not that tag, and the difference is
+        exactly what someone comparing an instance to a release needs.
+        """
+        code, out, _ = self._run("describe", "--tags", "--always", "--dirty")
         return out if code == 0 else ""
 
+    def commits_ahead_of(self, ref: str) -> int:
+        """How many commits HEAD carries that `ref` does not."""
+        code, out, _ = self._run("rev-list", "--count", f"{ref}..HEAD")
+        return int(out) if code == 0 and out.isdigit() else 0
+
     def contains(self, ref: str) -> bool:
         """Whether HEAD already includes that ref.
 
diff --git a/tests/framework/test_doctor.py b/tests/framework/test_doctor.py
index 4d0ac639..d88a2e76 100644
--- a/tests/framework/test_doctor.py
+++ b/tests/framework/test_doctor.py
@@ -13,6 +13,7 @@
     check_env_drift,
     check_exited,
     check_missing_secrets,
+    check_release,
     check_stale_code,
     diagnose,
     env_drift,
@@ -197,6 +198,43 @@ def test_an_unanswerable_question_reports_nothing():
     assert findings == []
 
 
+# ── the release this instance is on ──────────────────────────────────────
+
+class TestRelease:
+    """Doctor answers "what am I running, and is there something newer".
+
+    Both halves matter to an operator deciding whether tonight is an
+    update night, and neither was reported anywhere before: `stack
+    version` prints a constant from the working tree, which names a
+    hundred different trees between tags.
+    """
+
+    def test_a_newer_release_is_worth_saying(self):
+        finding = check_release("v0.3.0-beta.2", "v0.3.0-beta.3", up_to_date=False)
+
+        assert "v0.3.0-beta.3" in finding.title
+        assert finding.fix == "stack update"
+
+    def test_being_behind_is_not_an_error(self):
+        """Nothing is broken, and doctor's exit code gates scripts."""
+        finding = check_release("v0.3.0-beta.2", "v0.3.0-beta.3", up_to_date=False)
+        assert finding.is_error is False
+
+    def test_nothing_to_say_when_current(self):
+        assert check_release("v0.3.0-beta.3", "v0.3.0-beta.3", up_to_date=True) is None
+
+    def test_nothing_to_say_without_tags(self):
+        """A shallow clone, or a checkout with no releases fetched, cannot
+        answer the question. Silence beats a wrong answer."""
+        assert check_release("abc1234", "", up_to_date=False) is None
+
+    def test_says_the_answer_is_only_as_fresh_as_the_clone(self):
+        """Doctor does not reach the network, so the newest release it
+        knows is the newest this clone has fetched."""
+        finding = check_release("v0.3.0-beta.2", "v0.3.0-beta.3", up_to_date=False)
+        assert "clone" in finding.detail
+
+
 # ── findings ─────────────────────────────────────────────────────────────
 
 def test_env_drift_finding_is_actionable():
diff --git a/tests/framework/test_updater.py b/tests/framework/test_updater.py
index 771bd3d3..bfc4a083 100644
--- a/tests/framework/test_updater.py
+++ b/tests/framework/test_updater.py
@@ -15,7 +15,8 @@
 import pytest
 
 from stack.updater import (
-    Checkout, latest_tag, restart_targets, stale_stacklets, version_key,
+    Checkout, latest_tag, restart_targets, running_version, stale_stacklets,
+    version_key,
 )
 
 
@@ -91,6 +92,41 @@ def test_version_order_is_total(self):
         assert sorted(reversed(ordered), key=version_key) == ordered
 
 
+# ── What this checkout actually is ───────────────────────────────────────
+
+class TestRunningVersion:
+    """`VERSION` in the source is the last number someone typed.
+
+    Between tags it names a hundred different trees, which is how a
+    checkout 102 commits past beta.3 reports itself as beta.3. git
+    already answers this exactly: the nearest tag, the distance from it,
+    and the commit.
+    """
+
+    def test_on_a_release_it_is_the_release(self):
+        assert running_version("v0.3.0-beta.3", "0.3.0-beta.3") == "0.3.0-beta.3"
+
+    def test_past_a_release_it_says_how_far(self):
+        assert running_version("v0.3.0-beta.3-102-ge861bd5",
+                               "0.3.0-beta.3") == "0.3.0-beta.3-102-ge861bd5"
+
+    def test_uncommitted_work_is_part_of_the_answer(self):
+        """A dirty tree is not the tag, however close it sits."""
+        assert "dirty" in running_version("v0.3.0-beta.3-1-gabc123-dirty",
+                                          "0.3.0-beta.3")
+
+    def test_a_bumped_but_untagged_version_shows_both(self):
+        """The release gate bumps the constant before the tag exists, and
+        for that window the two disagree. Hiding either one is a lie."""
+        answer = running_version("v0.3.0-beta.3-4-gabc123", "0.3.0-beta.4")
+
+        assert "0.3.0-beta.4" in answer
+        assert "v0.3.0-beta.3-4-gabc123" in answer
+
+    def test_without_git_the_constant_is_all_there_is(self):
+        assert running_version("", "0.3.0-beta.3") == "0.3.0-beta.3"
+
+
 # ── What has to be restarted ─────────────────────────────────────────────
 
 class TestRestartTargets:
@@ -197,6 +233,15 @@ def test_knows_when_a_release_is_already_behind_it(self, repo):
         assert co.contains("v0.1.0") is True
         assert co.contains("v0.2.0") is True
 
+    def test_counts_how_far_ahead_of_a_release_it_is(self, repo):
+        """"Already past v0.3.0-beta.3" tells you the direction and not
+        the distance, which is the part that decides whether you care."""
+        co = Checkout(repo)
+        assert co.commits_ahead_of("v0.1.0") == 0
+
+        co.checkout("v0.2.0")
+        assert co.commits_ahead_of("v0.1.0") == 1
+
     def test_reports_what_a_jump_changes(self, repo):
         co = Checkout(repo)
         changed = co.changed_paths("v0.1.0", "v0.2.0")

From 21e8861a9f9baf355048a263c3eb27d1509163c4 Mon Sep 17 00:00:00 2001
From: Arthur <hello@arthware.dev>
Date: Sun, 20 Sep 2026 20:00:00 +0200
Subject: [PATCH 11/11] fix(doctor): print suggested fixes as runnable commands

Prefix suggested fixes with "to fix:" and print stack commands with the
`./` prefix, for example `./stack restart memory`. The JSON output keeps
the command without the prefix.
---
 lib/stack/cli.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/lib/stack/cli.py b/lib/stack/cli.py
index b15c096f..9ba2ed36 100644
--- a/lib/stack/cli.py
+++ b/lib/stack/cli.py
@@ -960,7 +960,13 @@ def missing_secrets(stacklet_id):
         mark = f"{RED}✗{RESET}" if finding.is_error else f"{ORANGE}⚠{RESET}"
         print(f"  {mark}  {BOLD}{finding.title}{RESET}")
         print(f"     {DIM}{finding.detail}{RESET}")
-        print(f"     {TEAL}{finding.fix}{RESET}\n")
+        # Labelled and copy-pasteable. The `./` goes on here rather than
+        # in the finding, so the data stays a bare command for anything
+        # reading the JSON, and a fix that is not a stack command (the
+        # stacktests path) is left exactly as written.
+        command = (f"./{finding.fix}" if finding.fix.startswith("stack ")
+                   else finding.fix)
+        print(f"     {DIM}to fix:{RESET} {TEAL}{command}{RESET}\n")
 
     print(f"  {doctor.summarise(findings)}\n")
     # Exit non-zero on errors so an agent or script can gate on it.