Version bump and docs update

Author: sirmalloc

README.md

@@ -47,6 +47,10 @@
 
 ## 🆕 Recent Updates
 
+### v2.2.27 - Portable configuration import and export
+
+- **📦 Config import/export** - Export the current TUI configuration to JSON, validate and preview imports, then replace all settings or merge only supplied fields while preserving local installation metadata and leaving the result unsaved for review.
+
 ### v2.2.25 - v2.2.26 - Fable usage, migrated usage API support, compaction accuracy, and rendering reliability
 
 - **🪄 Weekly Fable usage** - Added a `Weekly Fable Usage` widget with percentage, progress-bar, remaining-mode, and time-cursor controls.
@@ -273,6 +277,7 @@
 - **🖥️ Interactive TUI** - Built-in configuration interface using React/Ink
 - **🔎 Fast Widget Picker** - Add/change widgets by category with search and ranked matching
 - **⚙️ Global Options** - Apply consistent formatting across all widgets (padding, separators, bold, minimalist mode, and color overrides)
+- **📦 Portable Configurations** - Export settings to JSON and preview replace-or-merge imports for backups and sharing
 - **🚀 Cross-platform** - Works seamlessly with both Bun and Node.js
 - **🔧 Flexible Configuration** - Supports custom Claude Code config directory via `CLAUDE_CONFIG_DIR` environment variable
 - **📏 Smart Width Detection** - Automatically adapts to terminal width with flex separators
@@ -313,6 +318,7 @@ The interactive configuration tool provides a terminal UI where you can:
 - Configure flex separator behavior
 - Configure Claude Code status line refresh interval when supported
 - Edit custom text widgets
+- Export JSON backups and preview imported configs before replacing or merging settings
 - Install/uninstall to Claude Code settings
 - Preview your status line in real-time
 

docs/DEVELOPMENT.md

@@ -59,6 +59,8 @@ If you use a custom Claude config location, set `CLAUDE_CONFIG_DIR` and ccstatus
 
 Settings saves are atomic and preserve symlinked `settings.json` files by writing through the resolved target. Invalid or unreadable settings are never overwritten during load; `loadSettings()` returns in-memory defaults, records `getConfigLoadError()`, and renderer paths surface that state with an invalid-config warning badge. The TUI captures that load error, keeps a visible warning active, and guards both save paths with an overwrite confirmation until a valid configuration is saved.
 
+Configuration exports snapshot the live TUI settings and add an `exportedBy` package version. Imports reject newer schema versions before current-schema parsing, migrate supported older formats, and retain the source payload's present-key set so merge mode changes only explicitly supplied settings. `applyImport()` filters machine-local installation, schema-version, and update-message metadata; replace mode restores the current installation metadata, while merge mode preserves every omitted value.
+
 Usage-fetch tests spawn subprocess probes. Keep those probes sandboxed by setting `HOME`, `USERPROFILE`, `CLAUDE_CONFIG_DIR`, and proxy variables explicitly so tests cannot read or write a developer's live ccstatusline usage cache.
 
 ## Widget Data Sources

docs/USAGE.md

@@ -150,6 +150,20 @@ Gradients self-degrade where they can't render: at Basic or No Color levels, gra
 
 When ccstatusline is installed in Claude Code, the main menu includes **Configure Status Line**. Claude Code versions >=2.1.97 support `statusLine.refreshInterval`; ccstatusline can set it to `1-60` seconds, defaults fresh supported installs to `10` seconds, and removes the setting when the input is left empty.
 
+## Configuration Import and Export
+
+The TUI main menu can move configurations between machines or preserve a backup:
+
+- **Export Config** writes the current in-memory configuration to a JSON file, including edits that have not been saved to `settings.json` yet. The default destination is `~/ccstatusline-config.json`; parent directories are created as needed, and the export records the ccstatusline version that created it.
+- **Import Config** reads a JSON file, validates it, migrates supported older formats, rejects files from newer schema versions, and shows the effective changes before anything is applied.
+
+The import preview follows the highlighted action:
+
+- **Replace All** replaces user-facing settings with the validated import and current defaults for omitted fields.
+- **Merge** overlays only fields explicitly present in the imported file, preserving current values for omitted settings.
+
+Both modes keep machine-local installation metadata and ignore schema/update metadata from the imported file. Applying an import updates only the TUI's working configuration; review the result, then choose **Save & Exit** or press `Ctrl+S` to persist it.
+
 ## Settings Recovery
 
 If `settings.json` is unreadable or invalid, ccstatusline leaves the file unchanged, renders with built-in defaults for that run, and prepends an invalid-config warning badge to the status line. The TUI shows the same warning and asks for confirmation before either **Save & Exit** or `Ctrl+S` replaces the invalid file. Fix the JSON to preserve its contents, or confirm the save to replace it with the configuration currently shown in the TUI.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccstatusline",
-  "version": "2.2.26",
+  "version": "2.2.27",
   "bugs": {
     "url": "https://github.com/sirmalloc/ccstatusline/issues"
   },