Generated and pasted board backgrounds move into .backgrounds/ — the board root stops collecting the app's own pictures

New app-written background images (Theme tab ▸ Pattern, and Edit ▸ Paste
as Board Background) now land in a hidden `.backgrounds/` folder at
board root instead of beside index.md, matching the `.trash/` app-managed
pattern. `background.image` stores the qualified relative reference
(`.backgrounds/facets.png`); the resolver needed no change at all, since
it already accepted any relative path inside the board root — the same
mechanism that already resolved `art/backdrops/sunset.png` resolves the
new location for free. `BoardWriter.writeBoardImage` now creates its
destination folder if missing, since `.backgrounds/` won't exist until a
board's first generated or pasted background.

The Finder collision-ladder (`BoardStore.boardImageName`) is rescoped to
`.backgrounds/`'s own contents, and its overwrite-in-place check now
recognizes only the qualified form as "ours" — a legacy bare
`background.image: facets.png` from before this change is read as a
foreign reference rather than migrated, so a regeneration writes a fresh
`.backgrounds/` file and orphans the old one in place, per the no-migration
ruling. The Theme tab's Pattern/Solid mode-detection was updated to
recognize both the legacy and current spellings as the generator's own
output.

The board loader needed no change: `.backgrounds/` is a hidden,
non-UUID-shaped name, and `.skipsHiddenFiles` already keeps every hidden
entry off the lane walk before any name-based exclusion is consulted —
pinned with a new loader test. Deliberately did not add `.backgrounds` to
IntegrityRules' claimed-name/squatter-displacement table: that table
mirrors a specific existing DESIGN ruling this card doesn't amend.

Claude-Session: https://claude.ai/code/session_014PtZdPwqZuqEDLc6wZMtEy

KanbanTests/GeneratedBackgroundTests.swift

@@ -146,6 +146,25 @@ struct WriteBoardImageTests {
         let receipts = ledger.outstandingEntries()
         #expect(receipts.contains { $0.key.hasSuffix("/facets.png") })
     }
+
+    /// **`.backgrounds/` did not exist before this ruling** (2026-08-09), so the first board on a
+    /// Mac to ever generate or paste a background hands this call a folder nothing has made yet — the
+    /// call has to make it rather than fail, or every board's very first background write would.
+    @Test("The destination folder is created when it does not exist yet")
+    func createsTheDestinationFolderWhenMissing() throws {
+        let fixture = try makeBoard()
+        defer { fixture.tearDown() }
+        let backgroundsFolder = fixture.root.appendingPathComponent(
+            BoardBackdrop.backgroundsFolderName, isDirectory: true
+        )
+
+        let name = try BoardWriter.writeBoardImage(
+            data: png, named: "facets.png", inRoot: backgroundsFolder, operation: .setBoardBackground
+        )
+
+        #expect(name == "facets.png")
+        #expect(try fixture.data("\(BoardBackdrop.backgroundsFolderName)/facets.png") == png)
+    }
 }
 
 // MARK: - The gesture
@@ -154,7 +173,7 @@ struct WriteBoardImageTests {
 @Suite("BoardStore ▸ applyGeneratedBackground")
 struct GeneratedBackgroundWriteTests {
 
-    @Test("The picture lands in the folder and both subkeys point at it")
+    @Test("The picture lands in .backgrounds/ and both subkeys point at it")
     func writesTheFileAndTheFields() throws {
         let fixture = try makeBoard()
         defer { fixture.tearDown() }
@@ -162,11 +181,12 @@ struct GeneratedBackgroundWriteTests {
 
         #expect(store.applyGeneratedBackground(png: png, colorHex: "#E0E5EB"))
 
-        #expect(try fixture.data("facets.png") == png)
+        #expect(try fixture.data(".backgrounds/facets.png") == png)
         let after = try document(fixture)
         #expect(after.background == .valid("#E0E5EB"))
-        #expect(after.backgroundImage == .valid("facets.png"))
-        #expect(try fixture.indexText("").contains("background: {color: \"#E0E5EB\", image: \"facets.png\"}"))
+        #expect(after.backgroundImage == .valid(".backgrounds/facets.png"))
+        #expect(try fixture.indexText("")
+            .contains("background: {color: \"#E0E5EB\", image: \".backgrounds/facets.png\"}"))
         #expect(store.banners.oneShots.isEmpty)
     }
 
@@ -198,7 +218,7 @@ struct GeneratedBackgroundWriteTests {
         store.applyGeneratedBackground(png: png, colorHex: "#513D1A")
 
         let text = try fixture.indexText("")
-        #expect(text.contains("background: {color: \"#513D1A\", image: \"facets.png\"}"))
+        #expect(text.contains("background: {color: \"#513D1A\", image: \".backgrounds/facets.png\"}"))
         #expect(text.contains("project: lanework       # agent overlay"))
         #expect(text.contains("created: 2026-01-01T09:00:00Z"))
         #expect(text.contains("Board description."))
@@ -216,11 +236,10 @@ struct GeneratedBackgroundWriteTests {
         await reload(store)
         store.applyGeneratedBackground(png: otherPNG, colorHex: "#513D1A")
 
-        #expect(try fixture.data("facets.png") == otherPNG)
-        #expect(try document(fixture).backgroundImage == .valid("facets.png"))
-        // No ladder: the reload in between also seeds this board's `.gitignore`, so the listing is
-        // filtered to the pictures rather than compared whole.
-        #expect(try fixture.entryNames("").filter { $0.hasSuffix(".png") } == ["facets.png"])
+        #expect(try fixture.data(".backgrounds/facets.png") == otherPNG)
+        #expect(try document(fixture).backgroundImage == .valid(".backgrounds/facets.png"))
+        // No ladder: `.backgrounds/` holds exactly the one picture this store ever wrote to it.
+        #expect(try fixture.entryNames(".backgrounds") == ["facets.png"])
     }
 
     /// **The reroll's echo**: rolling again before the watcher has rounded the first write back must
@@ -235,55 +254,80 @@ struct GeneratedBackgroundWriteTests {
         store.applyGeneratedBackground(png: png, colorHex: "#E0E5EB")
         store.applyGeneratedBackground(png: otherPNG, colorHex: "#513D1A")
 
-        #expect(try fixture.data("facets.png") == otherPNG)
-        #expect(try fixture.entryNames("") == [Ident.lane1, "facets.png", "index.md"])
+        #expect(try fixture.data(".backgrounds/facets.png") == otherPNG)
+        #expect(try fixture.entryNames("") == [".backgrounds", Ident.lane1, "index.md"])
     }
 
-    /// **Somebody else's `facets.png` is never written through** — a file the user put in the board
-    /// folder is theirs, and the Finder ladder is how the app steps aside from a name it does not own.
-    @Test("A foreign file on the name pushes the generation to 'facets 2.png'")
+    /// **Somebody else's `.backgrounds/facets.png` is never written through** — a file the user put in
+    /// that folder is theirs, and the Finder ladder is how the app steps aside from a name it does not
+    /// own. A same-named file at board root — the legacy location — is a different question entirely
+    /// (`aLegacyBareReferenceIsNotOverwrittenInPlace`, below): it no longer sits anywhere this write
+    /// ever looks.
+    @Test("A foreign file on the name pushes the generation to '.backgrounds/facets 2.png'")
     func stepsAsideFromAForeignFile() throws {
         let fixture = try makeBoard()
         defer { fixture.tearDown() }
         let mine = Data("not the app's".utf8)
-        try fixture.file("facets.png", mine)
+        try fixture.file(".backgrounds/facets.png", mine)
         let (store, _) = try makeStore(fixture)
 
         store.applyGeneratedBackground(png: png, colorHex: "#E0E5EB")
 
-        #expect(try fixture.data("facets.png") == mine, "the user's file is untouched")
-        #expect(try fixture.data("facets 2.png") == png)
-        #expect(try document(fixture).backgroundImage == .valid("facets 2.png"))
+        #expect(try fixture.data(".backgrounds/facets.png") == mine, "the user's file is untouched")
+        #expect(try fixture.data(".backgrounds/facets 2.png") == png)
+        #expect(try document(fixture).backgroundImage == .valid(".backgrounds/facets 2.png"))
     }
 
     /// The same ladder when the board already names a *different* image: the hand-written path is
-    /// the escape hatch and stays on disk, and the generation lands beside it.
+    /// the escape hatch and stays on disk, and the generation lands beside it — inside `.backgrounds/`,
+    /// composing with the collision-ladder test above.
     @Test("A board naming another image keeps it and generates alongside")
     func keepsAHandWrittenImage() throws {
         let fixture = try makeBoard(background: "{image: sunset.jpg}")
         defer { fixture.tearDown() }
         try fixture.file("sunset.jpg", Data("photo".utf8))
-        try fixture.file("facets.png", Data("someone else's".utf8))
+        try fixture.file(".backgrounds/facets.png", Data("someone else's".utf8))
         let (store, _) = try makeStore(fixture)
 
         store.applyGeneratedBackground(png: png, colorHex: "#E0E5EB")
 
         #expect(try fixture.data("sunset.jpg") == Data("photo".utf8))
-        #expect(try document(fixture).backgroundImage == .valid("facets 2.png"))
+        #expect(try document(fixture).backgroundImage == .valid(".backgrounds/facets 2.png"))
     }
 
     /// A board whose generated file was deleted in Finder is a board with a broken backdrop, and
-    /// regenerating is exactly the repair — so the name is reused rather than laddered.
-    @Test("A missing file under our own name is rewritten, not laddered")
+    /// regenerating is exactly the repair — so the name is reused rather than laddered, **when the
+    /// reference is already the qualified `.backgrounds/` one this scheme writes**.
+    @Test("A missing file under our own qualified name is rewritten, not laddered")
     func rewritesAMissingFile() throws {
+        let fixture = try makeBoard(background: "{color: fern, image: .backgrounds/facets.png}")
+        defer { fixture.tearDown() }
+        let (store, _) = try makeStore(fixture)
+
+        store.applyGeneratedBackground(png: png, colorHex: "#E0E5EB")
+
+        #expect(try fixture.data(".backgrounds/facets.png") == png)
+        #expect(try document(fixture).backgroundImage == .valid(".backgrounds/facets.png"))
+    }
+
+    /// **Legacy stays where it is — no migration** (ruled 2026-08-09). A board whose `background.image`
+    /// still names a bare `facets.png` at board root — the shape every board carried before this
+    /// ruling — does not read as "ours to overwrite in place": only the qualified `.backgrounds/`
+    /// spelling does (`rewritesAMissingFile`, above). So a regeneration on a legacy board writes a
+    /// fresh `.backgrounds/facets.png` rather than touching the root-level file the field used to name
+    /// — even though nothing is actually there to protect in this case (the field names a file that
+    /// was never created), the point is the *reference's shape* decides, not disk contents.
+    @Test("A legacy bare reference is left alone; the regeneration writes a fresh .backgrounds/ file")
+    func aLegacyBareReferenceIsNotOverwrittenInPlace() throws {
         let fixture = try makeBoard(background: "{color: fern, image: facets.png}")
         defer { fixture.tearDown() }
         let (store, _) = try makeStore(fixture)
 
         store.applyGeneratedBackground(png: png, colorHex: "#E0E5EB")
 
-        #expect(try fixture.data("facets.png") == png)
-        #expect(try document(fixture).backgroundImage == .valid("facets.png"))
+        #expect(try fixture.data(".backgrounds/facets.png") == png)
+        #expect(try document(fixture).backgroundImage == .valid(".backgrounds/facets.png"))
+        #expect(!fixture.exists("facets.png"), "no legacy file was ever created — nothing to leave behind")
     }
 
     /// A locked board writes nothing at all — not the picture, not the fields.
@@ -295,7 +339,7 @@ struct GeneratedBackgroundWriteTests {
         store.enterVanishedRootLock()
 
         #expect(store.applyGeneratedBackground(png: png, colorHex: "#E0E5EB") == false)
-        #expect(!fixture.exists("facets.png"))
+        #expect(!fixture.exists(".backgrounds/facets.png"))
         #expect(try document(fixture).backgroundImage == .missing)
     }
 }
@@ -327,7 +371,7 @@ struct GeneratedBackgroundUndoTests {
         history.redo()
         let redone = try document(fixture)
         #expect(redone.background == .valid("#E0E5EB"))
-        #expect(redone.backgroundImage == .valid("facets.png"))
+        #expect(redone.backgroundImage == .valid(".backgrounds/facets.png"))
     }
 
     /// A prior colour comes back as itself rather than as an absence — the same reading `applyStyle`'s
@@ -362,8 +406,8 @@ struct GeneratedBackgroundUndoTests {
 
         history.undo()
         #expect(try document(fixture).background == .valid("#E0E5EB"))
-        #expect(try document(fixture).backgroundImage == .valid("facets.png"))
-        #expect(try fixture.data("facets.png") == otherPNG, "the first generation's bytes are gone")
+        #expect(try document(fixture).backgroundImage == .valid(".backgrounds/facets.png"))
+        #expect(try fixture.data(".backgrounds/facets.png") == otherPNG, "the first generation's bytes are gone")
     }
 
     /// A foreign edit to the field the step wrote stales it — the field-level predicate, applied to
@@ -437,7 +481,7 @@ struct SolidBackgroundWriteTests {
     /// does not delete the picture on disk — only the field that pointed at it. Undo has to have
     /// something to point back to (`SolidBackgroundUndoTests.restoresAPriorGeneratedImage`), and even
     /// without undo the file is the user's now, not litter the app cleans up on its own.
-    @Test("facets.png stays on disk when the board had one")
+    @Test(".backgrounds/facets.png stays on disk when the board had one")
     func leavesTheGeneratedFileOnDisk() throws {
         let fixture = try makeBoard()
         defer { fixture.tearDown() }
@@ -446,7 +490,7 @@ struct SolidBackgroundWriteTests {
 
         store.applySolidBackground(colorHex: "#513D1A")
 
-        #expect(try fixture.data("facets.png") == png, "the bytes are untouched")
+        #expect(try fixture.data(".backgrounds/facets.png") == png, "the bytes are untouched")
         #expect(try document(fixture).backgroundImage == .missing, "only the field is gone")
     }