feat(cli): add --data-dir flag to isolate local state

Add --data-dir option to all CLI commands, allowing users to override
the default ~/.paperclip root for config, context, database, logs, and
storage. Includes preAction hook to auto-derive --config and --context
paths when --data-dir is set. Add unit tests and doc updates.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cli/src/config/data-dir.ts

@@ -0,0 +1,48 @@
+import path from "node:path";
+import {
+  expandHomePrefix,
+  resolveDefaultConfigPath,
+  resolveDefaultContextPath,
+  resolvePaperclipInstanceId,
+} from "./home.js";
+
+export interface DataDirOptionLike {
+  dataDir?: string;
+  config?: string;
+  context?: string;
+  instance?: string;
+}
+
+export interface DataDirCommandSupport {
+  hasConfigOption?: boolean;
+  hasContextOption?: boolean;
+}
+
+export function applyDataDirOverride(
+  options: DataDirOptionLike,
+  support: DataDirCommandSupport = {},
+): string | null {
+  const rawDataDir = options.dataDir?.trim();
+  if (!rawDataDir) return null;
+
+  const resolvedDataDir = path.resolve(expandHomePrefix(rawDataDir));
+  process.env.PAPERCLIP_HOME = resolvedDataDir;
+
+  if (support.hasConfigOption) {
+    const hasConfigOverride = Boolean(options.config?.trim()) || Boolean(process.env.PAPERCLIP_CONFIG?.trim());
+    if (!hasConfigOverride) {
+      const instanceId = resolvePaperclipInstanceId(options.instance);
+      process.env.PAPERCLIP_INSTANCE_ID = instanceId;
+      process.env.PAPERCLIP_CONFIG = resolveDefaultConfigPath(instanceId);
+    }
+  }
+
+  if (support.hasContextOption) {
+    const hasContextOverride = Boolean(options.context?.trim()) || Boolean(process.env.PAPERCLIP_CONTEXT?.trim());
+    if (!hasContextOverride) {
+      process.env.PAPERCLIP_CONTEXT = resolveDefaultContextPath();
+    }
+  }
+
+  return resolvedDataDir;
+}