@edspencer/paddock 0.63.0 → 0.65.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.63.0",
+  "version": "0.65.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

package/packages/server/dist/adoptable.d.ts

@@ -123,6 +123,24 @@ export declare function isSweeperPrompt(preview: string): boolean;
  * to a real remote — the caller does not have to special-case it.
  */
 export declare function normalizeRemote(url: string): string;
+/**
+ * Every remote URL configured in a git checkout, normalised.
+ *
+ * Reads `.git/config` directly rather than shelling out to git: this runs for
+ * candidate directories behind a count rendered in a header, and a subprocess per
+ * candidate is exactly the cost that made checking the remote look unaffordable
+ * in the first place.
+ *
+ * Handles a linked WORKTREE, where `.git` is a FILE holding `gitdir: <path>` and
+ * the config lives in the MAIN repository's git dir — found by resolving the
+ * `commondir` pointer. This repo is developed with worktrees, so a contributor's
+ * `wt-*` checkout is a real case, not a hypothetical.
+ *
+ * Returns `[]` for anything unreadable or not a checkout at all. An INI parse is
+ * enough here — `url = …` inside a `[remote "…"]` section — because the question
+ * is only "does any remote name this repo", not "what is the exact config".
+ */
+export declare function gitRemotes(cwd: string): Promise<string[]>;
 /** The engine surface this module needs — narrowed so tests can fake it. */
 export interface AdoptableFleet {
     listAdoptableSessions(agentName: string, fromWorkingDir?: string): Promise<AdoptableSession[]>;

package/packages/server/dist/adoptable.js

@@ -216,7 +216,7 @@ export function normalizeRemote(url) {
  * enough here — `url = …` inside a `[remote "…"]` section — because the question
  * is only "does any remote name this repo", not "what is the exact config".
  */
-async function gitRemotes(cwd) {
+export async function gitRemotes(cwd) {
     const dot = path.join(cwd, ".git");
     const st = await fs.stat(dot).catch(() => null);
     if (st === null)

package/packages/server/dist/app.js

@@ -109,7 +109,9 @@ export async function buildApp(opts = {}) {
     // on a fatal misconfig (e.g. jwt mode without a JWKS URL) — fail closed.
     registerAuth(app, cfg.auth);
     // --- project layer + herdctl ------------------------------------------
-    const projects = new ProjectStore(cfg.projectsRoot);
+    const projects = new ProjectStore(cfg.projectsRoot, cfg.dataDir, {
+        warn: (message) => app.log.warn(message),
+    });
     await projects.init();
     // The user's own MCP servers, under `claude.mcpServers: host` (#691 step 5).
     // Read BEFORE the service is constructed because every keeper's agent config

package/packages/server/dist/claude-home.js

@@ -471,7 +471,15 @@ export async function ensureClaudeHome(cfg, env = process.env, probeKeychain = p
         }
         if (present.length > 0) {
             report.notices.push({
-                level: "info",
+                // `warn`, not `info`, and deliberately (#706). `cli/paddock.ts` sets
+                // LOG_LEVEL=warn unless `--verbose`, so at `info` this was filtered out
+                // on the `npx` path — the documented install route, and the one
+                // population the notice exists for. It is not noise at `warn` because it
+                // is already inside `present.length > 0`: it fires only for someone who
+                // HAS ~/.claude instruction files that are not being loaded. An empty
+                // ~/.claude, or `instructions: host`, prints nothing at all. Do not
+                // "tidy" it back to `info` — that reintroduces #706.
+                level: "warn",
                 message: `Claude instructions: this instance's own only (\`claude.instructions: own\`). Your ` +
                     `~/.claude ${present.join(", ")} ${present.length === 1 ? "is" : "are"} NOT loaded — ` +
                     `set \`claude.instructions: host\` (or PADDOCK_CLAUDE_INSTRUCTIONS=host) to share ` +

package/packages/server/dist/cli/import-chats.js

@@ -126,7 +126,7 @@ async function main() {
     if (args.dataDir !== undefined)
         process.env.PADDOCK_DATA_DIR = args.dataDir;
     const cfg = loadPaddockConfig();
-    const projects = new ProjectStore(cfg.projectsRoot);
+    const projects = new ProjectStore(cfg.projectsRoot, cfg.dataDir);
     const herdctl = new HerdctlService(cfg);
     const project = await projects.get(args.project);
     // Register the keepers so the agent this imports INTO exists and its `.chats/`

package/packages/server/dist/git.d.ts

@@ -46,6 +46,8 @@ export declare class GitService {
     private readonly author;
     /** Cached repo-detection result for `projectsRoot` (null = not yet checked). */
     private repoFlag;
+    /** Cached per-directory repo detection, keyed by resolved path (#597 / #206). */
+    private readonly repoAt;
     /**
      * @param projectsRoot Absolute path to the projects root the service operates on.
      * @param author Commit identity used when Paddock commits on a project's behalf.
@@ -62,9 +64,36 @@ export declare class GitService {
      * Whether the backing store is a git working tree. Cached after the first
      * successful check (repo-ness doesn't change under a running server); a thrown
      * git / missing-binary error resolves to `false`.
+     *
+     * Store-wide, so it still gates the store-wide operations ({@link dirtyCounts},
+     * {@link remote}, {@link push}). The PER-PROJECT surface asks
+     * {@link isRepoAt} about the project's own working directory instead — see
+     * that method for why the two had to be separated.
      */
     isRepo(): Promise<boolean>;
-    /** Force the next `isRepo()` to re-check (e.g. after `git init` at runtime). */
+    /**
+     * Whether `dir` is inside a git working tree, cached per directory.
+     *
+     * The per-project git surface used to gate on {@link isRepo} — "is the PROJECTS
+     * ROOT a repo?" — which was right only while every project's tree lived under
+     * that root. It stopped being right twice over (issue #597, issue #206):
+     *
+     *  - a project whose working directory is a linked checkout outside the root
+     *    would report "not a repo" whenever the root itself wasn't one, hiding the
+     *    Changes tab for the exact directory that IS a repo;
+     *  - conversely a non-repo directory inside a repo root would claim to be one.
+     *
+     * Asking about the directory the project actually works in answers both. For
+     * every pre-existing shape it returns what {@link isRepo} did, because a
+     * project dir under a repo root is itself inside that work tree.
+     *
+     * Probing rather than requiring is the house style: nothing here refuses a
+     * directory for not being a repo, it just doesn't light up the git features.
+     */
+    isRepoAt(dir: string): Promise<boolean>;
+    /** One `rev-parse`, false on any failure (missing binary, missing dir, not a repo). */
+    private probeRepo;
+    /** Force the next repo check to re-run (e.g. after `git init` at runtime). */
     resetRepoCache(): void;
     /**
      * Status for one project's subtree. Returns `{ repo: false }` when the store
@@ -120,6 +149,20 @@ export declare class GitService {
      * when the store isn't a repo.
      */
     dirtyCounts(): Promise<Record<string, number>>;
+    /**
+     * Uncommitted-file count for ONE directory's own repository.
+     *
+     * The companion to {@link dirtyCounts} for a project whose working directory
+     * lives outside `projectsRoot` (issue #206). That method answers the whole grid
+     * in a single `git status` over the store, which is why it is cheap — and also
+     * why it structurally cannot see a linked checkout: it buckets paths by their
+     * first segment relative to the store, and a directory outside it has no such
+     * segment. This one costs a subprocess, so callers use it only for the projects
+     * the cheap sweep genuinely cannot cover.
+     *
+     * Returns 0 for a directory that isn't a repo, matching "nothing to report".
+     */
+    dirtyCountAt(dir: string): Promise<number>;
     /** Push the current branch to origin (sets upstream on first push). */
     push(): Promise<{
         pushed: boolean;

package/packages/server/dist/git.js

@@ -52,6 +52,8 @@ export class GitService {
     author;
     /** Cached repo-detection result for `projectsRoot` (null = not yet checked). */
     repoFlag = null;
+    /** Cached per-directory repo detection, keyed by resolved path (#597 / #206). */
+    repoAt = new Map();
     /**
      * @param projectsRoot Absolute path to the projects root the service operates on.
      * @param author Commit identity used when Paddock commits on a project's behalf.
@@ -74,25 +76,60 @@ export class GitService {
      * Whether the backing store is a git working tree. Cached after the first
      * successful check (repo-ness doesn't change under a running server); a thrown
      * git / missing-binary error resolves to `false`.
+     *
+     * Store-wide, so it still gates the store-wide operations ({@link dirtyCounts},
+     * {@link remote}, {@link push}). The PER-PROJECT surface asks
+     * {@link isRepoAt} about the project's own working directory instead — see
+     * that method for why the two had to be separated.
      */
     async isRepo() {
         if (this.repoFlag !== null)
             return this.repoFlag;
+        this.repoFlag = await this.probeRepo(this.projectsRoot);
+        return this.repoFlag;
+    }
+    /**
+     * Whether `dir` is inside a git working tree, cached per directory.
+     *
+     * The per-project git surface used to gate on {@link isRepo} — "is the PROJECTS
+     * ROOT a repo?" — which was right only while every project's tree lived under
+     * that root. It stopped being right twice over (issue #597, issue #206):
+     *
+     *  - a project whose working directory is a linked checkout outside the root
+     *    would report "not a repo" whenever the root itself wasn't one, hiding the
+     *    Changes tab for the exact directory that IS a repo;
+     *  - conversely a non-repo directory inside a repo root would claim to be one.
+     *
+     * Asking about the directory the project actually works in answers both. For
+     * every pre-existing shape it returns what {@link isRepo} did, because a
+     * project dir under a repo root is itself inside that work tree.
+     *
+     * Probing rather than requiring is the house style: nothing here refuses a
+     * directory for not being a repo, it just doesn't light up the git features.
+     */
+    async isRepoAt(dir) {
+        const key = path.resolve(dir);
+        const cached = this.repoAt.get(key);
+        if (cached !== undefined)
+            return cached;
+        const found = await this.probeRepo(key);
+        this.repoAt.set(key, found);
+        return found;
+    }
+    /** One `rev-parse`, false on any failure (missing binary, missing dir, not a repo). */
+    async probeRepo(dir) {
         try {
-            const out = await this.git(this.projectsRoot, [
-                "rev-parse",
-                "--is-inside-work-tree",
-            ]);
-            this.repoFlag = out.trim() === "true";
+            const out = await this.git(dir, ["rev-parse", "--is-inside-work-tree"]);
+            return out.trim() === "true";
         }
         catch {
-            this.repoFlag = false;
+            return false;
         }
-        return this.repoFlag;
     }
-    /** Force the next `isRepo()` to re-check (e.g. after `git init` at runtime). */
+    /** Force the next repo check to re-run (e.g. after `git init` at runtime). */
     resetRepoCache() {
         this.repoFlag = null;
+        this.repoAt.clear();
     }
     /**
      * Status for one project's subtree. Returns `{ repo: false }` when the store
@@ -100,7 +137,9 @@ export class GitService {
      * `projectDir`.
      */
     async projectStatus(projectDir) {
-        if (!(await this.isRepo())) {
+        // Per-DIRECTORY, not store-wide: callers pass the project's workingDir, which
+        // may be a linked checkout outside `projectsRoot` entirely (#597 / #206).
+        if (!(await this.isRepoAt(projectDir))) {
             return { repo: false, files: [], clean: true };
         }
         let branch;
@@ -188,7 +227,7 @@ export class GitService {
      * (they're listed by `projectStatus`). Returns "" when not a repo / no diff.
      */
     async projectDiff(projectDir, file) {
-        if (!(await this.isRepo()))
+        if (!(await this.isRepoAt(projectDir)))
             return "";
         const args = ["diff", "HEAD", "--", file ?? "."];
         try {
@@ -259,7 +298,7 @@ export class GitService {
      * Omitting `paths` keeps the legacy commit-the-whole-subtree behavior.
      */
     async commitProject(projectDir, message, paths) {
-        if (!(await this.isRepo()))
+        if (!(await this.isRepoAt(projectDir)))
             return { committed: false, error: "not a repo" };
         const msg = message.trim() || "Update project";
         let pathspec;
@@ -325,6 +364,35 @@ export class GitService {
             return {};
         }
     }
+    /**
+     * Uncommitted-file count for ONE directory's own repository.
+     *
+     * The companion to {@link dirtyCounts} for a project whose working directory
+     * lives outside `projectsRoot` (issue #206). That method answers the whole grid
+     * in a single `git status` over the store, which is why it is cheap — and also
+     * why it structurally cannot see a linked checkout: it buckets paths by their
+     * first segment relative to the store, and a directory outside it has no such
+     * segment. This one costs a subprocess, so callers use it only for the projects
+     * the cheap sweep genuinely cannot cover.
+     *
+     * Returns 0 for a directory that isn't a repo, matching "nothing to report".
+     */
+    async dirtyCountAt(dir) {
+        if (!(await this.isRepoAt(dir)))
+            return 0;
+        try {
+            const out = await this.git(dir, [
+                "status",
+                "--porcelain=v1",
+                "-z",
+                "--untracked-files=all",
+            ]);
+            return parsePorcelainZ(out).length;
+        }
+        catch {
+            return 0;
+        }
+    }
     /** Push the current branch to origin (sets upstream on first push). */
     async push() {
         if (!(await this.isRepo()))

package/packages/server/dist/management-ops.js

@@ -308,7 +308,39 @@ export function buildManagementOps(ctx, params) {
                 name: project.name,
                 dir: project.dir,
                 workingDir: project.workingDir,
-                repoBacked: project.repoBacked === true,
+                managed: project.managed === true,
+                ...(project.repo ? { repo: project.repo } : {}),
+                ...(project.path ? { path: project.path } : {}),
+                agentRegistered,
+            };
+        },
+        // Promotion (#470), sharing create's gate. Same discipline: the SAME two calls,
+        // in the same order, that `POST /api/projects/:slug/promote` makes — store
+        // promote, then agent re-registration. Every guard (already unmanaged, the
+        // root workspace, an existing checkout dir, a bad URL) and the rollback to an
+        // untouched notebook on clone failure live in `ProjectStore.promote` (#213).
+        promoteProject: async (projectSlug, repo) => {
+            const project = await deps.projects.promote(projectSlug, repo);
+            // Non-fatal, as in the route — but it matters more than it does for create:
+            // re-registering is what re-symlinks the NEW working dir at the project's
+            // existing `.chats/` store, which is what keeps its chats listed + resumable.
+            let agentRegistered = true;
+            try {
+                await deps.herdctl.ensureProjectAgent(project);
+            }
+            catch {
+                agentRegistered = false;
+            }
+            return {
+                slug: project.slug,
+                name: project.name,
+                dir: project.dir,
+                workingDir: project.workingDir,
+                // #206 replaced `repoBacked` with the `managed` axis. Promotion always
+                // lands on `managed: false` — that IS what promoting means now — but read
+                // it off the project rather than hard-coding, so this reports what the
+                // store actually did.
+                managed: project.managed,
                 ...(project.repo ? { repo: project.repo } : {}),
                 agentRegistered,
             };
@@ -404,12 +436,20 @@ export function enforceManagementPolicy(ops, principal) {
     const write = {
         currentProjectSlug: w.currentProjectSlug,
         currentSessionId: w.currentSessionId,
+        // The project block is offered when EITHER of its verbs is granted; the
+        // per-tool filter (`managementToolFilter`) is what hides the other one, so a
+        // client scoped to just one of them isn't denied both.
+        projectsMcpEnabled: w.projectsMcpEnabled &&
+            (isOperationAllowed(scope, "create_project") || isOperationAllowed(scope, "promote_project")),
         // Instance-level, so there is no project to scope-check — only the verb.
-        projectsMcpEnabled: w.projectsMcpEnabled && isOperationAllowed(scope, "create_project"),
         createProject: (input) => {
             assertOperation(principal, "create_project");
             return w.createProject(input);
         },
+        // Promotion DOES name an existing project, so unlike create it is scope-checked
+        // against `projects` too — a client confined to one project must not restructure
+        // another.
+        promoteProject: (projectSlug, repo) => guard("promote_project", projectSlug, () => w.promoteProject(projectSlug, repo)),
         createChat: (projectSlug, prompt, o) => guard("create_chat", projectSlug, () => w.createChat(projectSlug, prompt, o)),
         // NOTE: `fork_chat_batch` is a convenience wrapper that calls this same
         // callback N times, so it is gated on `fork_chat` here AND on

package/packages/server/dist/management-policy.d.ts

@@ -66,7 +66,7 @@ export interface ManagementPrincipal {
 /** Read-only operations: no state change, no turn started. */
 export declare const READ_OPERATIONS: readonly ["list_projects", "list_chats", "read_chat"];
 /** Chat write operations. The first four START TURNS (see the RCE note above). */
-export declare const WRITE_OPERATIONS: readonly ["create_project", "create_chat", "fork_chat", "send_message", "fork_chat_batch", "archive_chat", "unarchive_chat"];
+export declare const WRITE_OPERATIONS: readonly ["create_project", "promote_project", "create_chat", "fork_chat", "send_message", "fork_chat_batch", "archive_chat", "unarchive_chat"];
 /** Unified trigger operations (Epic T / T3). `list_triggers` is the read one. */
 export declare const TRIGGER_OPERATIONS: readonly ["list_triggers", "set_trigger", "remove_trigger", "run_trigger"];
 /** Every operation the management surface knows about. */
@@ -81,8 +81,9 @@ export declare const ALL_OPERATIONS: readonly string[];
 /**
  * Operations that grant code execution on the host, and so define the risk class
  * a write scope really is. A superset of {@link TURN_SPAWNING_OPERATIONS}:
- * `create_project` starts no turn, but it clones a CALLER-SUPPLIED git URL and
- * creates instance-level state, which belongs in the same warning.
+ * `create_project`/`promote_project` start no turn, but they clone a
+ * CALLER-SUPPLIED git URL and create (or restructure) instance-level state, which
+ * belongs in the same warning.
  */
 export declare const HIGH_RISK_OPERATIONS: readonly string[];
 export declare const TURN_SPAWNING_OPERATIONS: readonly string[];

package/packages/server/dist/management-policy.js

@@ -34,6 +34,7 @@ export const READ_OPERATIONS = ["list_projects", "list_chats", "read_chat"];
 /** Chat write operations. The first four START TURNS (see the RCE note above). */
 export const WRITE_OPERATIONS = [
     "create_project",
+    "promote_project",
     "create_chat",
     "fork_chat",
     "send_message",
@@ -64,11 +65,13 @@ export const ALL_OPERATIONS = [
 /**
  * Operations that grant code execution on the host, and so define the risk class
  * a write scope really is. A superset of {@link TURN_SPAWNING_OPERATIONS}:
- * `create_project` starts no turn, but it clones a CALLER-SUPPLIED git URL and
- * creates instance-level state, which belongs in the same warning.
+ * `create_project`/`promote_project` start no turn, but they clone a
+ * CALLER-SUPPLIED git URL and create (or restructure) instance-level state, which
+ * belongs in the same warning.
  */
 export const HIGH_RISK_OPERATIONS = [
     "create_project",
+    "promote_project",
     "create_chat",
     "fork_chat",
     "fork_chat_batch",

package/packages/server/dist/project-paths.d.ts

@@ -66,11 +66,79 @@ export declare function isValidRepoUrl(url: string): boolean;
  */
 export declare function repoCheckoutName(repo: string): string;
 /**
- * Resolve a project's working directory (keeper cwd) from its metadata dir + repo
- * URL: the nested checkout for a repo-backed project, else the metadata dir
- * itself for a notebook project (issue #187).
+ * Whether `child` is `parent` itself or lives underneath it. Both are resolved
+ * first, so this compares real path strings rather than the caller's spelling
+ * (it does NOT follow symlinks — callers that care resolve them beforehand).
+ *
+ * The `+ path.sep` is load-bearing: a plain `startsWith(parent)` would call
+ * `/data/projects-old` a child of `/data/projects`.
+ */
+export declare function isPathInside(child: string, parent: string): boolean;
+/**
+ * Resolve a project's working directory (keeper cwd) from its metadata dir plus
+ * whichever backing field is set:
+ *
+ *  - **`linkedPath`** (issue #206) — the cwd IS that directory, returned
+ *    verbatim, used in place with no copy. Applies on BOTH sides of the
+ *    managed/unmanaged axis: an unmanaged project links a code checkout you
+ *    already have, a managed one nominates where its notes should live.
+ *  - **`repo`** (issue #187) — the nested checkout Paddock cloned.
+ *  - **neither** — the metadata dir itself.
+ *
+ * `linkedPath` WINS over `repo`, which is why the two are not mutually exclusive:
+ * `repo` alongside a path is an ACQUISITION hint (clone here if the path is
+ * missing) plus a remote-match for adoption (`adoptable.ts`, #659) and a re-clone
+ * hint for disaster recovery. It never moves the cwd off the nominated path.
+ */
+export declare function workingDirFor(dir: string, repo?: string, linkedPath?: string): string;
+/** The subset of `project.yaml` that decides a project's shape. */
+export interface ProjectBacking {
+    managed?: boolean;
+    repo?: string;
+    path?: string;
+}
+/**
+ * Whether Paddock looks after this project's own files — the real axis, and the
+ * one that replaced the overloaded `repoBacked` boolean (issue #206).
+ *
+ * **managed** — Paddock curates `CLAUDE.md` / `OVERVIEW.md` / `CHANGELOG.md`
+ * here. This is what "notebook" used to mean.
+ * **unmanaged** — the content is code that you or your agents source-control
+ * OUTSIDE Paddock. Paddock never writes project files into it.
+ *
+ * Whether a git repo sits behind it is an INDEPENDENT question (just which of
+ * `path`/`repo` are set), not a type. See `docs/DESIGN-backing-store.md` §2 goal
+ * 4: the base store is a plain directory and git is an optional layer.
+ *
+ * ## The default is derived, never constant
+ *
+ * `managed ?? !(repo || path)` — an absent key means "whatever this project's
+ * backing implies". That is load-bearing for the upgrade path: every existing
+ * `project.yaml` predates the key, and if absent meant `true`, every existing
+ * repo-backed project would flip to managed on upgrade and the sweeper would
+ * start writing `CLAUDE.md` into somebody's checkout. New projects write the key
+ * explicitly, so the derivation only ever has to serve legacy files.
+ */
+export declare function isManaged(backing: ProjectBacking): boolean;
+/**
+ * Where a project's CURATED CONTENT lives — `OVERVIEW.md`, `CHANGELOG.md` and
+ * `CLAUDE.md`, the three files the sweeper writes.
+ *
+ * Content follows the working directory; application state does not. So:
+ *
+ *  - **managed** ⇒ the working dir. For a classic notebook that IS the metadata
+ *    dir (unchanged). For a managed project with an external `path`, the curated
+ *    files live out there with the content — an accepted consequence being that
+ *    they then do NOT live in the Paddock data dir.
+ *  - **unmanaged** ⇒ the metadata dir, always. The working dir is somebody
+ *    else's tree and Paddock does not write project files into it; `OVERVIEW.md`
+ *    and `CHANGELOG.md` are still curated, just sidecarred (issue #187), and
+ *    `CLAUDE.md` is not curated at all (the checkout owns its own).
+ *
+ * `project.yaml` and `.chats/` are NOT content and never move — see
+ * {@link import("./projects.js").ProjectStore.dirFor}.
  */
-export declare function workingDirFor(dir: string, repo?: string): string;
+export declare function contentDirFor(dir: string, backing: ProjectBacking): string;
 export declare class ProjectError extends Error {
     readonly code: "not_found" | "exists" | "invalid" | "not_directory";
     constructor(message: string, code: "not_found" | "exists" | "invalid" | "not_directory");

package/packages/server/dist/project-paths.js

@@ -74,13 +74,85 @@ export function repoCheckoutName(repo) {
     return safe || "repo";
 }
 /**
- * Resolve a project's working directory (keeper cwd) from its metadata dir + repo
- * URL: the nested checkout for a repo-backed project, else the metadata dir
- * itself for a notebook project (issue #187).
+ * Whether `child` is `parent` itself or lives underneath it. Both are resolved
+ * first, so this compares real path strings rather than the caller's spelling
+ * (it does NOT follow symlinks — callers that care resolve them beforehand).
+ *
+ * The `+ path.sep` is load-bearing: a plain `startsWith(parent)` would call
+ * `/data/projects-old` a child of `/data/projects`.
+ */
+export function isPathInside(child, parent) {
+    const c = path.resolve(child);
+    const p = path.resolve(parent);
+    return c === p || c.startsWith(p + path.sep);
+}
+/**
+ * Resolve a project's working directory (keeper cwd) from its metadata dir plus
+ * whichever backing field is set:
+ *
+ *  - **`linkedPath`** (issue #206) — the cwd IS that directory, returned
+ *    verbatim, used in place with no copy. Applies on BOTH sides of the
+ *    managed/unmanaged axis: an unmanaged project links a code checkout you
+ *    already have, a managed one nominates where its notes should live.
+ *  - **`repo`** (issue #187) — the nested checkout Paddock cloned.
+ *  - **neither** — the metadata dir itself.
+ *
+ * `linkedPath` WINS over `repo`, which is why the two are not mutually exclusive:
+ * `repo` alongside a path is an ACQUISITION hint (clone here if the path is
+ * missing) plus a remote-match for adoption (`adoptable.ts`, #659) and a re-clone
+ * hint for disaster recovery. It never moves the cwd off the nominated path.
  */
-export function workingDirFor(dir, repo) {
+export function workingDirFor(dir, repo, linkedPath) {
+    if (linkedPath)
+        return linkedPath;
     return repo ? path.join(dir, repoCheckoutName(repo)) : dir;
 }
+/**
+ * Whether Paddock looks after this project's own files — the real axis, and the
+ * one that replaced the overloaded `repoBacked` boolean (issue #206).
+ *
+ * **managed** — Paddock curates `CLAUDE.md` / `OVERVIEW.md` / `CHANGELOG.md`
+ * here. This is what "notebook" used to mean.
+ * **unmanaged** — the content is code that you or your agents source-control
+ * OUTSIDE Paddock. Paddock never writes project files into it.
+ *
+ * Whether a git repo sits behind it is an INDEPENDENT question (just which of
+ * `path`/`repo` are set), not a type. See `docs/DESIGN-backing-store.md` §2 goal
+ * 4: the base store is a plain directory and git is an optional layer.
+ *
+ * ## The default is derived, never constant
+ *
+ * `managed ?? !(repo || path)` — an absent key means "whatever this project's
+ * backing implies". That is load-bearing for the upgrade path: every existing
+ * `project.yaml` predates the key, and if absent meant `true`, every existing
+ * repo-backed project would flip to managed on upgrade and the sweeper would
+ * start writing `CLAUDE.md` into somebody's checkout. New projects write the key
+ * explicitly, so the derivation only ever has to serve legacy files.
+ */
+export function isManaged(backing) {
+    return backing.managed ?? !(backing.repo || backing.path);
+}
+/**
+ * Where a project's CURATED CONTENT lives — `OVERVIEW.md`, `CHANGELOG.md` and
+ * `CLAUDE.md`, the three files the sweeper writes.
+ *
+ * Content follows the working directory; application state does not. So:
+ *
+ *  - **managed** ⇒ the working dir. For a classic notebook that IS the metadata
+ *    dir (unchanged). For a managed project with an external `path`, the curated
+ *    files live out there with the content — an accepted consequence being that
+ *    they then do NOT live in the Paddock data dir.
+ *  - **unmanaged** ⇒ the metadata dir, always. The working dir is somebody
+ *    else's tree and Paddock does not write project files into it; `OVERVIEW.md`
+ *    and `CHANGELOG.md` are still curated, just sidecarred (issue #187), and
+ *    `CLAUDE.md` is not curated at all (the checkout owns its own).
+ *
+ * `project.yaml` and `.chats/` are NOT content and never move — see
+ * {@link import("./projects.js").ProjectStore.dirFor}.
+ */
+export function contentDirFor(dir, backing) {
+    return isManaged(backing) ? workingDirFor(dir, backing.repo, backing.path) : dir;
+}
 export class ProjectError extends Error {
     code;
     constructor(message, code) {