@edspencer/paddock 0.63.0 → 0.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.63.0",
+  "version": "0.64.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,8 +308,9 @@ 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,
             };
         },

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) {

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

@@ -175,6 +175,61 @@ export interface ProjectYaml {
      * (like `slug`/`started`).
      */
     repo?: string;
+    /**
+     * Whether Paddock looks after this project's own files (issue #206).
+     *
+     * `true` — Paddock curates `CLAUDE.md` / `OVERVIEW.md` / `CHANGELOG.md` here;
+     * this is what "notebook" used to mean. `false` — the content is code that you
+     * or your agents source-control OUTSIDE Paddock, and Paddock never writes
+     * project files into it.
+     *
+     * This is the real axis. It replaced the derived `repoBacked` boolean, which
+     * was one flag doing four jobs and broke the moment a fifth backing shape
+     * appeared. Whether a git repo sits behind the project is INDEPENDENT of this
+     * and is not a type — it is just which of `path`/`repo` are set.
+     *
+     * **Optional on disk, and the default is DERIVED rather than constant:**
+     * `managed ?? !(repo || path)` (see
+     * {@link import("./project-paths.js").isManaged}). Every `project.yaml` written
+     * before this key existed relies on that: were an absent value to mean `true`,
+     * every existing repo-backed project would flip to managed on upgrade and the
+     * sweeper would begin writing `CLAUDE.md` into its checkout. `create()` always
+     * writes the key explicitly, so the derivation only ever serves legacy files.
+     *
+     * `managed: true` together with `repo` is REJECTED at creation rather than
+     * silently ignored — Paddock curating files into a repo it also clones is not a
+     * combination with a sensible meaning.
+     */
+    managed?: boolean;
+    /**
+     * Absolute path to the directory holding this project's content (issue #206).
+     *
+     * Applies on BOTH sides of the managed axis, which is what makes it a location
+     * rather than a type:
+     *
+     *  - **unmanaged + `path`** — LINK a code checkout you already have
+     *    (`~/Code/foo`), used in place with no copy: its real history, branches and
+     *    remotes. Paddock writes nothing into it (no `.chats/`, no sidecar
+     *    `.gitignore`, no `CLAUDE.md`); transcripts stay in `<slug>/.chats/` via
+     *    `ensureProjectChats`'s two-argument split. Transcripts key on this cwd, so
+     *    prior `claude` sessions run there by hand are offered for adoption, and
+     *    `claude.transcripts: host` / per-directory `~/.claude.json` MCP servers
+     *    finally mean something for a code project.
+     *  - **managed + `path`** — nominate where your NOTES live. The curated trio
+     *    (`OVERVIEW.md`/`CHANGELOG.md`/`CLAUDE.md`) follows the path, so those files
+     *    end up outside the Paddock data dir.
+     *
+     * Either way `project.yaml` (the registry entry Paddock discovers projects by
+     * scanning for) and `.chats/` (Paddock's own state) stay in
+     * `<projectsRoot>/<slug>/`.
+     *
+     * Acquisition when the path does NOT exist: with `repo`, Paddock clones into it;
+     * for a managed project, Paddock creates it; otherwise the create is rejected.
+     *
+     * Set at creation and immutable thereafter (like `slug`/`started`/`repo`) — the
+     * cwd is baked into every transcript path, so moving it would strand history.
+     */
+    path?: string;
     /**
      * Scheduled chat sessions for this project (issue #265 / DD-2), keyed by a
      * stable schedule name. Each value is herdctl's `ScheduleSchema` shape (plus the
@@ -211,22 +266,46 @@ export interface Project extends ProjectYaml {
      *  empty string means "Unsorted". */
     group: string;
     /**
-     * Absolute path to the project's METADATA directory — the per-slug dir in the
-     * instance data repo that holds `project.yaml`, `OVERVIEW.md`, `CHANGELOG.md`,
-     * `.chats/`, and (for a notebook project) `CLAUDE.md`. For a NOTEBOOK project
-     * this is also the keeper's cwd; for a REPO-BACKED project the cwd is
-     * {@link workingDir} (the nested checkout) instead — see #187.
+     * Absolute path to the project's METADATA directory — the per-slug dir under
+     * `projectsRoot`. Always holds `project.yaml` (the registry entry Paddock
+     * discovers projects by scanning for, so it can never move) and `.chats/`
+     * (Paddock's own state, and what backup tooling points at).
+     *
+     * It ALSO holds the curated trio (`OVERVIEW.md`/`CHANGELOG.md`/`CLAUDE.md`)
+     * unless the project is managed with an external `path`, in which case those
+     * follow the content — see {@link contentDir}.
      */
     dir: string;
     /**
-     * The keeper agent's working directory (cwd). For a notebook project this
-     * equals {@link dir}; for a repo-backed project it's the nested checkout
-     * (`<dir>/<repo-name>`), so the repo's own `CLAUDE.md` + git tooling apply
-     * (issue #187). Always concrete in the DTO.
+     * The keeper agent's working directory (cwd): {@link ProjectYaml.path} verbatim
+     * when set, else the nested checkout for a `repo`-backed project (#187), else
+     * {@link dir}. Always concrete in the DTO.
+     *
+     * This — not {@link dir} — is the directory the git surface reports on, which
+     * is what issue #597 was: the Changes tab read `dir`, so it showed the metadata
+     * directory rather than the code the project is actually about.
      */
     workingDir: string;
-    /** Whether this project is backed by an external git repo (issue #187). */
-    repoBacked: boolean;
+    /**
+     * Where the sweeper's curated trio lives — {@link workingDir} for a managed
+     * project, {@link dir} for an unmanaged one (issue #206). Always concrete.
+     *
+     * Equals {@link dir} in every pre-#206 shape; it differs only for a managed
+     * project with an external `path`.
+     */
+    contentDir: string;
+    /**
+     * Whether Paddock curates this project's own files — ALWAYS concrete in the
+     * DTO, derived via `managed ?? !(repo || path)` so legacy files keep their
+     * meaning (issue #206).
+     *
+     * This replaced `repoBacked`, which conflated four separate questions into one
+     * boolean and broke as soon as a fifth backing shape appeared. Each consumer
+     * now takes the fact it actually needs: the sweeper's `CLAUDE.md` suppression
+     * and the promote guard key on `managed`; the git surface keys on whether
+     * {@link workingDir} is a git working tree, asked per directory.
+     */
+    managed: boolean;
     /** Whether OVERVIEW.md exists in the project dir (sweep-curated context). */
     hasOverview: boolean;
     /** Always present in the DTO (defaults to []). */
@@ -259,6 +338,25 @@ export interface CreateProjectInput {
      * a notebook project (the classic type).
      */
     repo?: string;
+    /**
+     * Whether Paddock should curate this project's own files (issue #206). Absent ⇒
+     * derived as `!(repo || path)`, so a plain create is managed and a create that
+     * names a backing is not. `managed: true` together with `repo` is REJECTED.
+     */
+    managed?: boolean;
+    /**
+     * Absolute path to the directory this project's content lives in (issue #206).
+     *
+     * Validated at create time: absolute, and outside `projectsRoot` / the data dir
+     * / every other project's working directory. Immutable thereafter. If it does
+     * not exist, Paddock clones `repo` into it when one is given, creates it for a
+     * managed project, and otherwise rejects the create.
+     *
+     * There is deliberately NO requirement that it be a git repository — Paddock
+     * probes for git and lights up the git features when it finds one, exactly as
+     * it already does for the projects root.
+     */
+    path?: string;
 }
 /** Partial metadata update (slug + started are immutable). */
 export type UpdateProjectInput = Partial<Pick<ProjectYaml, "name" | "status" | "domain" | "group" | "visibility" | "summary" | "links" | "model" | "permissionMode" | "maxTurns" | "docker">> & {