docs: enhance state management documentation and clarify error handling

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
 

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(.{});

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..],