diff --git a/.claude/rules/nix-workflow.md b/.claude/rules/nix-workflow.md
new file mode 100644
index 0000000..1e734dc
--- /dev/null
+++ b/.claude/rules/nix-workflow.md
@@ -0,0 +1,88 @@
+# Nix Workflow
+
+This rule provides guidance on Nix usage in the StackOne SDK.
+
+## Development Environment
+
+The project uses `flake.nix` to define the development environment with `nix develop`.
+
+### Adding Development Tools
+
+To add a new tool to the development environment, add it to `buildInputs` in `flake.nix`:
+
+```nix
+buildInputs = with pkgs; [
+  # runtime
+  nodejs_24
+  pnpm_10
+
+  # formatting and linting tools
+  oxlint  # includes tsgolint
+  oxfmt
+
+  # your new tool here
+  new-tool
+];
+```
+
+## CI Workflow
+
+CI uses `nix profile install` via the `.github/actions/setup-nix/action.yaml` composite action.
+
+### Adding Tools to CI Jobs
+
+Specify tools in the `tools` input of the setup-nix action:
+
+```yaml
+- name: Setup Nix
+  uses: ./.github/actions/setup-nix
+  with:
+    tools: nodejs_24 pnpm_10 oxlint oxfmt
+```
+
+The action installs packages using:
+
+```bash
+nix profile install --inputs-from . nixpkgs#tool1 nixpkgs#tool2
+```
+
+### CI Tool Configuration
+
+- **Default tools**: `nodejs_24 pnpm_10` (defined in action.yaml)
+- **Skip pnpm install**: Set `skip-pnpm-install: 'true'` for jobs that don't need node dependencies
+
+### Example: Adding a New Tool to Lint Job
+
+```yaml
+lint:
+  runs-on: ubuntu-latest
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+    - name: Setup Nix
+      uses: ./.github/actions/setup-nix
+      with:
+        tools: nodejs_24 pnpm_10 oxlint oxfmt new-tool
+    - name: Run Lint
+      run: pnpm run lint
+```
+
+## Build Flags
+
+Always use these flags when running Nix build commands locally:
+
+```bash
+--print-build-logs --show-trace
+```
+
+Example:
+
+```bash
+nix build --print-build-logs --show-trace
+nix flake check --print-build-logs --show-trace
+```
+
+## Notes
+
+- Some packages bundle multiple tools (e.g., `oxlint` includes `tsgolint`)
+- Check nixpkgs for package contents before adding redundant dependencies
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index d8b2005..27712c0 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -41,7 +41,7 @@ jobs:
       - name: Setup Nix
         uses: ./.github/actions/setup-nix
         with:
-          tools: nodejs_24 pnpm_10 oxlint oxfmt similarity nixfmt tsgolint
+          tools: nodejs_24 pnpm_10 oxlint oxfmt
       - name: Run Lint
         run: pnpm run lint
 
diff --git a/CLAUDE.md b/CLAUDE.md
index e5b0871..404e78a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,6 +15,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 | **pnpm-usage**           | All files      | pnpm commands and troubleshooting                  |
 | **git-workflow**         | All files      | Commit conventions, branch strategy, PR guidelines |
 | **development-workflow** | All files      | Code style, file naming, project conventions       |
+| **nix-workflow**         | All files      | Nix development environment and CI setup           |
 | **typescript-patterns**  | `**/*.ts`      | Type safety, exhaustiveness checks, clean code     |
 | **typescript-testing**   | `**/*.test.ts` | Vitest, MSW mocking, fs-fixture                    |
 | **file-operations**      | `**/*.ts`      | Native fetch API patterns and error handling       |
diff --git a/flake.lock b/flake.lock
index cd54cf2..58bdca6 100644
--- a/flake.lock
+++ b/flake.lock
@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1768149890,
-        "narHash": "sha256-iihg1oHkVkYHD1pFQifGEP+Rw1g+LZQyDNbtAqpXtNM=",
+        "lastModified": 1768395095,
+        "narHash": "sha256-ZhuYJbwbZT32QA95tSkXd9zXHcdZj90EzHpEXBMabaw=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "4d113fe1f7bb454435a5cabae6cd283e64191bb7",
+        "rev": "13868c071cc73a5e9f610c47d7bb08e5da64fdd5",
         "type": "github"
       },
       "original": {
diff --git a/flake.nix b/flake.nix
index eb0c5a3..b85367a 100644
--- a/flake.nix
+++ b/flake.nix
@@ -31,7 +31,6 @@
               # formatting and linting tools
               similarity
               nixfmt
-              tsgolint
               oxlint
               oxfmt