docs: document workspace and safe onboarding

test-workspace-tracking.py

@@ -0,0 +1,47 @@
+"""Check root tracking on fictional data; never stage the real workspace."""
+
+from pathlib import Path
+import subprocess
+import tempfile
+
+
+def check(ignore_rules):
+    with tempfile.TemporaryDirectory(prefix="wealthledger-tracking-") as directory:
+        root = Path(directory)
+
+        def git(*args):
+            return subprocess.check_output(
+                ["git", "-C", str(root), *args], text=True
+            )
+
+        git("init", "--quiet")
+        allowed = {".gitignore", "AGENTS.md", "README.md", "test-workspace-tracking.py"}
+        for name in allowed:
+            (root / name).write_text("fictional fixture\n")
+        (root / ".gitignore").write_text(ignore_rules)
+        for name in ("frontend", "backend", "docs", "specs"):
+            nested = root / name
+            nested.mkdir()
+            subprocess.run(["git", "init", "--quiet", str(nested)], check=True)
+        for name in (
+            "frontend/source.ts", "backend/prisma/dev.db", "docs/README.md",
+            "specs/README.md", "statement-imports/report.csv", "private.db",
+            "private.db-wal", ".env", ".env.example", "audit.pdf",
+            "design/preview.html", "todo/notes.md", "references/source.md",
+            ".agents/local.md", "unknown-directory/data.txt", "unknown-file.txt",
+        ):
+            target = root / name
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text("fictional private data\n")
+        before = {p.relative_to(root): p.read_bytes() for p in root.rglob("*")
+                  if p.is_file() and ".git" not in p.relative_to(root).parts[:1]}
+        git("add", ".")
+        assert set(git("ls-files").splitlines()) == allowed
+        assert all((root / p).read_bytes() == content for p, content in before.items())
+        assert all((root / name / ".git").is_dir()
+                   for name in ("frontend", "backend", "docs", "specs"))
+
+
+if __name__ == "__main__":
+    check(Path(__file__).with_name(".gitignore").read_text())
+    print("PASS: only root allowlist staged; fictional data and nested Git preserved")