From 8d659a07546892bf254a145e893f2de262e00218 Mon Sep 17 00:00:00 2001
From: richen604 <56615615+richen604@users.noreply.github.com>
Date: Wed, 8 Jan 2025 17:54:06 -0800
Subject: [PATCH] docs: enhance state management documentation and clarify
 error handling

---
 README.md                        | 23 +++++++++++++----------
 build.zig                        |  1 +
 MARKETPLACE.md => marketplace.md |  0
 src/fs/symlink.zig               | 10 +++++-----
 4 files changed, 19 insertions(+), 15 deletions(-)
 rename MARKETPLACE.md => marketplace.md (100%)

diff --git a/README.md b/README.md
index 89a0824..1d26d67 100644
--- a/README.md
+++ b/README.md
@@ -288,31 +288,34 @@ target = "~/.config/alacritty/alacritty.toml"
 
 ### State Management
 
-Dotkit promotes explicit state management through clear separation of:
+Dotkit manages both static configurations and state files through explicit declarations:
 
-1. **Static Configuration** - Version controlled, reproducible files
-2. **State Files** - User-specific, mutable data that should live outside version control
+1. **Static Configuration** - Static files 
+2. **State Files** - User-specific, mutable data
 
-This is an entirely optional feature, but it is highly recommended.
+State files are an optional feature, but it is highly recommended regarding system design.
+Dotfile configurations often hold dynamic state 
 
 ```toml
+
+# state is false by default
 [[files]]
 source = "./alacritty/alacritty.toml"
 target = "~/.config/alacritty/alacritty.toml"
-state = false  # default: static config file
 
 [[files]]
 source = "./nvim/sessions"
 target = "~/.local/share/nvim/sessions"
-state = true   # marks as mutable state directory
+state = true   # marks as managed state directory
 ```
 
 This approach:
 - Makes state management explicit and intentional
-- Prevents accidental commits of personal data
-- Simplifies sharing configurations
-- Provides clear upgrade paths
-- Works well with backup systems
+- Provides controlled state file management
+- Enables proper NixOS integration
+- Simplifies configuration sharing
+- Supports automated backup/restore workflows
+- Allows for state file versioning when desired
 
 ## Command Line Interface
 
diff --git a/build.zig b/build.zig
index f366bc4..d12597d 100644
--- a/build.zig
+++ b/build.zig
@@ -1,6 +1,7 @@
 const std = @import("std");
 const builtin = @import("builtin");
 
+// TODO: refactor: reorganize modules into a single struct
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
diff --git a/MARKETPLACE.md b/marketplace.md
similarity index 100%
rename from MARKETPLACE.md
rename to marketplace.md
diff --git a/src/fs/symlink.zig b/src/fs/symlink.zig
index 7be72c7..0e96e00 100644
--- a/src/fs/symlink.zig
+++ b/src/fs/symlink.zig
@@ -159,13 +159,13 @@ pub const SymlinkManager = struct {
     fn checkCircularLink(_: *SymlinkManager, source: []const u8, target: []const u8) !void {
         // If target would be created inside the source path, it's circular
         if (std.mem.startsWith(u8, target, source)) {
-            return error.CircularLink;
+            return err.DotkitError.CircularLink;
         }
 
         // If source is a file, check if target would create a directory with the same name
         const source_stat = std.fs.cwd().statFile(source) catch |e| {
             return switch (e) {
-                error.FileNotFound => error.SourceNotFound,
+                error.FileNotFound => err.DotkitError.SourceNotFound,
                 else => e,
             };
         };
@@ -178,17 +178,17 @@ pub const SymlinkManager = struct {
             var iter = target_components;
             while (iter.next()) |component| {
                 if (std.mem.eql(u8, component, source_basename)) {
-                    return error.CircularLink;
+                    return err.DotkitError.CircularLink;
                 }
             }
         }
     }
 
     fn expandPath(allocator: std.mem.Allocator, path: []const u8) ![]u8 {
-        if (path.len == 0) return error.InvalidPath;
+        if (path.len == 0) return err.DotkitError.InvalidPath;
 
         if (path[0] == '~') {
-            const home = std.posix.getenv("HOME") orelse return error.HomeNotFound;
+            const home = std.posix.getenv("HOME") orelse return err.DotkitError.HomeNotFound;
             return std.fmt.allocPrint(allocator, "{s}{s}", .{
                 home,
                 path[1..],