stackone-ai 2.0.0__tar.gz → 2.3.0__tar.gz

stackone_ai-2.3.0/.claude/rules/nix-workflow.md

@@ -0,0 +1,84 @@
+# Nix Workflow
+
+This rule provides guidance on Nix usage in the StackOne AI Python SDK.
+
+## Development Environment
+
+The project uses `flake.nix` with flake-parts to define the development environment. Enter it with `nix develop`.
+
+### Adding Development Tools
+
+To add a new tool to the development environment, add it to `buildInputs` in `flake.nix`:
+
+```nix
+devShells.default = pkgs.mkShellNoCC {
+  buildInputs = with pkgs; [
+    uv
+    ty
+    just
+    nixfmt
+
+    # your new tool here
+    new-tool
+  ];
+};
+```
+
+### Treefmt and Git Hooks
+
+The flake includes:
+
+- **treefmt-nix**: Unified formatting (nixfmt, ruff, oxfmt)
+- **git-hooks.nix**: Pre-commit hooks (gitleaks, treefmt, ty)
+
+These are automatically installed when entering the dev shell.
+
+## 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: uv ty just bun pnpm_10
+```
+
+The action installs packages using:
+
+```bash
+nix profile install --inputs-from . nixpkgs#tool1 nixpkgs#tool2
+```
+
+### CI Tool Configuration
+
+- **Default tools**: `uv ty just` (defined in action.yaml)
+- **Skip uv sync**: Set `skip-uv-sync: 'true'` for jobs that don't need Python dependencies
+
+### Example: Adding a New Tool to CI Job
+
+```yaml
+ci:
+  runs-on: ubuntu-latest
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        submodules: true
+    - name: Setup Nix
+      uses: ./.github/actions/setup-nix
+      with:
+        tools: uv ty just new-tool
+    - name: Run Lint
+      run: just lint
+```
+
+## Notes
+
+- The project uses flake-parts for modular flake configuration
+- Git submodules are initialised automatically in dev shell and CI
+- MCP mock server dependencies (pnpm) are installed for testing

stackone_ai-2.3.0/.claude/skills/release-please/SKILL.md

@@ -0,0 +1,51 @@
+# Release Please Trigger
+
+Trigger a release-please PR for a specific version.
+
+## Usage
+
+```
+/release-please <version>
+```
+
+## Examples
+
+```
+/release-please 2.3.0
+/release-please 3.0.0
+```
+
+## Instructions
+
+When this skill is invoked with a version argument:
+
+1. **Validate the version format**: Ensure the version follows semantic versioning (X.Y.Z format)
+
+2. **Create a new branch**: Create a branch named `chore/trigger-release-<version>`
+
+   ```bash
+   git switch -c chore/trigger-release-<version>
+   ```
+
+3. **Create an empty commit with Release-As trailer**: The commit message must include the `Release-As: <version>` trailer to trigger release-please
+
+   ```bash
+   git commit --allow-empty -m "chore: trigger release <version>
+
+   Release-As: <version>"
+   ```
+
+4. **Push the branch and create a PR**:
+
+   ```bash
+   git push -u origin chore/trigger-release-<version>
+   gh pr create --title "chore: trigger release <version>" --body "Trigger release-please to create version <version>."
+   ```
+
+5. **Report the PR URL** to the user
+
+## Notes
+
+- The `Release-As` trailer in the commit message tells release-please to use that specific version
+- Once the PR is merged to main, release-please will automatically create a release PR with the specified version
+- The release PR will update CHANGELOG.md, version files, and create a GitHub release when merged

stackone_ai-2.3.0/.github/actions/setup-nix/action.yaml

@@ -0,0 +1,50 @@
+name: "Setup Nix"
+description: "Install Nix and configure cache"
+inputs:
+  tools:
+    description: 'Space-separated list of nixpkgs packages to install (e.g., "uv ty just")'
+    required: false
+    default: "uv ty just"
+  skip-uv-sync:
+    description: "Skip uv sync step (useful for jobs that do not need Python dependencies)"
+    required: false
+    default: "false"
+runs:
+  using: "composite"
+  steps:
+    - name: Install Nix
+      uses: cachix/install-nix-action@0b0e072294b088b73964f1d72dfdac0951439dbd # v31.8.4
+      with:
+        github_access_token: ${{ github.token }}
+
+    - name: Install tools from nixpkgs
+      shell: bash
+      run: |
+        tools="${{ inputs.tools }}"
+        packages=""
+        for tool in $tools; do
+          packages="$packages nixpkgs#$tool"
+        done
+        nix profile install --inputs-from . $packages
+
+    - name: Initialise git submodules
+      if: inputs.skip-uv-sync != 'true'
+      shell: bash
+      run: |
+        # Only initialise if submodules exist but are not yet checked out
+        if [ -f .gitmodules ] && [ ! -f vendor/stackone-ai-node/package.json ]; then
+          git submodule update --init --recursive
+        fi
+
+    - name: Install Python dependencies
+      if: inputs.skip-uv-sync != 'true'
+      shell: bash
+      run: uv sync --all-extras --locked
+
+    - name: Install MCP mock server dependencies
+      if: inputs.skip-uv-sync != 'true'
+      shell: bash
+      run: |
+        if [ -f vendor/stackone-ai-node/package.json ]; then
+          cd vendor/stackone-ai-node && pnpm install --frozen-lockfile
+        fi

{stackone_ai-2.0.0 → stackone_ai-2.3.0}/.github/dependabot.yaml

@@ -16,21 +16,9 @@ updates:
       - dependencies
       - python
     groups:
-      dev-dependencies:
+      python-minor-patch:
         patterns:
-          - "pytest*"
-          - "ruff"
-          - "ty"
-          - "pre-commit"
-        update-types:
-          - minor
-          - patch
-      ai-frameworks:
-        patterns:
-          - "openai*"
-          - "langchain*"
-          - "crewai*"
-          - "mcp*"
+          - "*"
         update-types:
           - minor
           - patch

{stackone_ai-2.0.0 → stackone_ai-2.3.0}/.github/workflows/ci.yaml

@@ -20,66 +20,60 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
 
       - name: Setup Nix
         uses: ./.github/actions/setup-nix
+        with:
+          tools: gitleaks
+          skip-uv-sync: "true"
 
       - name: Run Gitleaks
-        run: nix develop --command just gitleaks
+        run: gitleaks detect --source . --config .gitleaks.toml
 
   ci:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.13"]
-        include:
-          - python-version: "3.11"
-            sync-extras: "--all-extras"
-          - python-version: "3.13"
-            sync-extras: "--all-extras"
-    env:
-      STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
       - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: true
 
       - name: Setup Nix
         uses: ./.github/actions/setup-nix
-
-      - name: Install dependencies
-        run: nix develop --command just install ${{ matrix.sync-extras }}
+        with:
+          tools: uv ty just bun pnpm_10 typescript-go
 
       - name: Run Lint
-        run: nix develop --command just lint
+        run: just lint
 
       - name: Run Ty
-        run: nix develop --command just ty
+        run: just ty
 
       - name: Run Tests
-        run: nix develop --command just test
+        run: just test
 
   coverage:
     runs-on: ubuntu-latest
     if: github.ref == 'refs/heads/main'
-    env:
-      STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: true
 
       - name: Setup Nix
         uses: ./.github/actions/setup-nix
-
-      - name: Install dependencies
-        run: nix develop --command just install --all-extras
+        with:
+          tools: uv just bun pnpm_10 typescript-go
 
       - name: Run Tests with Coverage
-        run: nix develop --command just coverage
+        run: just coverage
 
       - name: Create Coverage Badge
         uses: jaywcjlove/coverage-badges-cli@4e8975aa2628e3329126e7eee36724d07ed86fda # v2.2.0

{stackone_ai-2.0.0 → stackone_ai-2.3.0}/.github/workflows/nix-flake-update.yaml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Setup Nix
         uses: ./.github/actions/setup-nix
@@ -35,7 +35,7 @@ jobs:
       - name: Create Pull Request
         id: create-pr
         if: steps.check-changes.outputs.changed == 'true'
-        uses: peter-evans/create-pull-request@98357b18bf14b5342f975ff684046ec3b2a07725 # v8.0.0
+        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           commit-message: "chore(deps): update nix flake inputs"

stackone_ai-2.3.0/.github/workflows/nix-flake.yaml

@@ -0,0 +1,35 @@
+name: "CI: Flake check"
+
+on:
+  push:
+    paths:
+      - "flake.nix"
+      - "flake.lock"
+      - ".github/workflows/nix-flake.yaml"
+      - ".github/actions/setup-nix/**"
+  pull_request:
+    paths:
+      - "flake.nix"
+      - "flake.lock"
+      - ".github/workflows/nix-flake.yaml"
+      - ".github/actions/setup-nix/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Check flake syntax and structure
+  flake-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@4e002c8ec80594ecd40e759629461e26c8abed15 # v31.9.0
+        with:
+          github_access_token: ${{ github.token }}
+
+      - name: Check flake
+        run: nix flake check --all-systems --print-build-logs --show-trace

stackone_ai-2.3.0/.github/workflows/release.yaml

@@ -0,0 +1,66 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@16a9c90856f42705d54a6fda1823352bdc62cf38 # v4.4.0
+        id: release
+        with:
+          config-file: .release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      # Update uv.lock when release PR is created/updated
+      - name: Checkout repository (for PR update)
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        if: ${{ steps.release.outputs.pr }}
+        with:
+          ref: ${{ fromJSON(steps.release.outputs.pr).headBranchName }}
+
+      - name: Setup Nix (for PR update)
+        if: ${{ steps.release.outputs.pr }}
+        uses: ./.github/actions/setup-nix
+        with:
+          skip-uv-sync: "true"
+
+      - name: Update uv.lock
+        if: ${{ steps.release.outputs.pr }}
+        run: |
+          nix develop --command uv lock
+          if git diff --quiet uv.lock; then
+            echo "uv.lock is already up to date"
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git add uv.lock
+            git commit -m "chore: update uv.lock"
+            git push
+          fi
+
+      # Only release to PyPI when a new release is created
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        if: ${{ steps.release.outputs.release_created }}
+
+      - name: Setup Nix
+        if: ${{ steps.release.outputs.release_created }}
+        uses: ./.github/actions/setup-nix
+        with:
+          skip-uv-sync: "true"
+
+      - name: Build and publish package
+        if: ${{ steps.release.outputs.release_created }}
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          nix develop --command just build
+          nix develop --command just publish

stackone_ai-2.3.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/stackone-ai-node"]
+	path = vendor/stackone-ai-node
+	url = https://github.com/StackOneHQ/stackone-ai-node.git

stackone_ai-2.3.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "2.3.0"
+}

{stackone_ai-2.0.0 → stackone_ai-2.3.0}/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [2.3.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.1.1...stackone-ai-v2.3.0) (2026-01-29)
+
+
+### Bug Fixes
+
+* **nix:** replace deprecated nixfmt-rfc-style with nixfmt ([#114](https://github.com/StackOneHQ/stackone-ai-python/issues/114)) ([10627b4](https://github.com/StackOneHQ/stackone-ai-python/commit/10627b441745806f3b57a7b1cdba296ef722b00f))
+
+
+### Miscellaneous Chores
+
+* trigger release 2.3.0 ([#130](https://github.com/StackOneHQ/stackone-ai-python/issues/130)) ([a28d0a6](https://github.com/StackOneHQ/stackone-ai-python/commit/a28d0a6fbcf703dd640d3255fa4171046ea225c7))
+
+## [2.1.1](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.1.0...stackone-ai-v2.1.1) (2026-01-22)
+
+
+### Bug Fixes
+
+* **ci:** skip mock server install in release workflow [ENG-11910] ([#111](https://github.com/StackOneHQ/stackone-ai-python/issues/111)) ([377d766](https://github.com/StackOneHQ/stackone-ai-python/commit/377d766a276b444e84fee5af95f3d56db7e0b89b))
+
+## [2.1.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.0.0...stackone-ai-v2.1.0) (2026-01-22)
+
+
+### Features
+
+* **nix:** integrate uv2nix for Python dependency management ([#88](https://github.com/StackOneHQ/stackone-ai-python/issues/88)) ([ee67062](https://github.com/StackOneHQ/stackone-ai-python/commit/ee67062d1a6628c9b549f2ad69c0c1d7bdde6d97))
+
+
+### Bug Fixes
+
+* **ci:** add submodules checkout to coverage job ([#85](https://github.com/StackOneHQ/stackone-ai-python/issues/85)) ([4cf907a](https://github.com/StackOneHQ/stackone-ai-python/commit/4cf907a49ac288f368ebbfa3a5dc59a0194bf54a))
+
+
+### Documentation
+
+* deepwiki badge ([#97](https://github.com/StackOneHQ/stackone-ai-python/issues/97)) ([d8b0234](https://github.com/StackOneHQ/stackone-ai-python/commit/d8b02346b6a77377b7c0356e636edcf2eac47096))
+* **readme:** improve Nix development environment setup instructions ([#94](https://github.com/StackOneHQ/stackone-ai-python/issues/94)) ([2d6f6c2](https://github.com/StackOneHQ/stackone-ai-python/commit/2d6f6c224d1119a5a0254934ff542a0572f44c06))
+* **readme:** reorganise installation section ([#72](https://github.com/StackOneHQ/stackone-ai-python/issues/72)) ([3cde479](https://github.com/StackOneHQ/stackone-ai-python/commit/3cde4794739e95479409396adc3b6e3b01eb3d33))
+* **rules:** add nix-workflow rule ([#106](https://github.com/StackOneHQ/stackone-ai-python/issues/106)) ([b10c164](https://github.com/StackOneHQ/stackone-ai-python/commit/b10c164142ede3ce37b96a27b0e73452d6de50e6))
+
 ## [2.0.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v0.3.4...stackone-ai-v2.0.0) (2025-12-29)
 
 

{stackone_ai-2.0.0 → stackone_ai-2.3.0}/CLAUDE.md

@@ -8,6 +8,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **Skills** (`.claude/skills/`): Manually invoked for specific integrations.
 - **Cursor rules** (`.cursor/rules/`): Symlinks to `.claude/rules/` for consistency.
 
+## Available Skills
+
+| Skill              | Usage                       | Description                                        |
+| ------------------ | --------------------------- | -------------------------------------------------- |
+| **release-please** | `/release-please <version>` | Trigger a release-please PR for a specific version |
+
 ## Available Rules
 
 | Rule                         | Applies To          | Description                                        |
@@ -15,6 +21,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 | **git-workflow**             | All files           | Commit conventions, branch strategy, PR guidelines |
 | **development-workflow**     | All files           | Code style, file naming, project conventions       |
 | **release-please-standards** | All files           | Release versioning with release-please             |
+| **nix-workflow**             | All files           | Nix development environment and CI configuration   |
 | **no-relative-imports**      | `**/*.py`           | Enforce absolute imports in Python files           |
 | **package-installation**     | `**/pyproject.toml` | UV package management standards                    |
 | **uv-scripts**               | `scripts/**/*.py`   | Utility script standards with UV                   |

{stackone_ai-2.0.0 → stackone_ai-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackone-ai
-Version: 2.0.0
+Version: 2.3.0
 Summary: agents performing actions on your SaaS
 Author-email: StackOne <support@stackone.com>
 License-File: LICENSE
@@ -8,11 +8,12 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
+Requires-Python: >=3.10
 Requires-Dist: bm25s>=0.2.2
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: langchain-core>=0.1.0
@@ -34,6 +35,9 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://badge.fury.io/py/stackone-ai.svg)](https://badge.fury.io/py/stackone-ai)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/StackOneHQ/stackone-ai-python)](https://github.com/StackOneHQ/stackone-ai-python/releases)
 [![Coverage](https://stackonehq.github.io/stackone-ai-python/badges.svg)](https://stackonehq.github.io/stackone-ai-python/html/)
+[![DeepWiki](https://img.shields.io/badge/DeepWiki-StackOneHQ%2Fstackone--ai--python-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/StackOneHQ/stackone-ai-python)
+
+<!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->
 
 StackOne AI provides a unified interface for accessing various SaaS tools through AI-friendly APIs.
 
@@ -47,7 +51,7 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
   - Glob pattern filtering with patterns like `"hris_*"` and exclusions `"!hris_delete_*"`
   - Provider and action filtering
   - Multi-account support
-- **Meta Tools** (Beta): Dynamic tool discovery and execution based on natural language queries
+- **Utility Tools** (Beta): Dynamic tool discovery and execution based on natural language queries
 - Integration with popular AI frameworks:
   - OpenAI Functions
   - LangChain Tools
@@ -60,30 +64,6 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
 
 ## Installation
 
-### Using Nix (Recommended for Development)
-
-If you have [Nix](https://nixos.org/) installed with flakes enabled:
-
-```bash
-# Enter development environment (auto-installs dependencies and git hooks)
-nix develop
-
-# Format code
-nix fmt
-
-# Run checks
-nix flake check
-```
-
-The Nix development environment includes:
-
-- Python with uv package manager
-- Automatic dependency installation
-- Git hooks (treefmt + ty) auto-configured
-- Consistent environment across all platforms
-
-### Using pip/uv
-
 ```bash
 pip install 'stackone-ai[mcp]'
 
@@ -333,16 +313,16 @@ result = crew.kickoff()
 
 ## Feedback Collection
 
-The SDK includes a feedback collection tool (`meta_collect_tool_feedback`) that allows users to submit feedback about their experience with StackOne tools. This tool is automatically included in the toolset and is designed to be invoked by AI agents after user permission.
+The SDK includes a feedback collection tool (`tool_feedback`) that allows users to submit feedback about their experience with StackOne tools. This tool is automatically included in the toolset and is designed to be invoked by AI agents after user permission.
 
 ```python
 from stackone_ai import StackOneToolSet
 
 toolset = StackOneToolSet()
 
-# Get the feedback tool (included with "meta_*" pattern or all tools)
-tools = toolset.fetch_tools(actions=["meta_*"])
-feedback_tool = tools.get_tool("meta_collect_tool_feedback")
+# Get the feedback tool (included with "tool_*" pattern or all tools)
+tools = toolset.fetch_tools(actions=["tool_*"])
+feedback_tool = tools.get_tool("tool_feedback")
 
 # Submit feedback (typically invoked by AI after user consent)
 result = feedback_tool.call(
@@ -357,23 +337,23 @@ result = feedback_tool.call(
 - "Are you ok with sending feedback to StackOne? The LLM will take care of sending it."
 - Only call the tool after the user explicitly agrees.
 
-## Meta Tools (Beta)
+## Utility Tools (Beta)
 
-Meta tools enable dynamic tool discovery and execution without hardcoding tool names.
+Utility tools enable dynamic tool discovery and execution without hardcoding tool names.
 
 ### Basic Usage
 
 ```python
-# Get meta tools for dynamic discovery
+# Get utility tools for dynamic discovery
 tools = toolset.fetch_tools(actions=["hris_*"])
-meta_tools = tools.meta_tools()
+utility_tools = tools.utility_tools()
 
 # Search for relevant tools using natural language
-filter_tool = meta_tools.get_tool("meta_search_tools")
+filter_tool = utility_tools.get_tool("tool_search")
 results = filter_tool.call(query="manage employees", limit=5)
 
 # Execute discovered tools dynamically
-execute_tool = meta_tools.get_tool("meta_execute_tool")
+execute_tool = utility_tools.get_tool("tool_execute")
 result = execute_tool.call(toolName="hris_list_employees", params={"limit": 10})
 ```
 
@@ -386,7 +366,41 @@ For more examples, check out the [examples/](examples/) directory:
 - [OpenAI Integration](examples/openai_integration.py)
 - [LangChain Integration](examples/langchain_integration.py)
 - [CrewAI Integration](examples/crewai_integration.py)
-- [Meta Tools](examples/meta_tools_example.py)
+- [Utility Tools](examples/utility_tools_example.py)
+
+## Development
+
+### Using Nix (Recommended)
+
+This project includes a Nix flake for reproducible development environments. All development tools are defined in [flake.nix](./flake.nix) and provided via Nix.
+
+#### Installing Nix
+
+```bash
+# Install Nix with flakes enabled (if not already installed)
+curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | \
+  sh -s -- install
+
+# If flakes are not enabled, enable them with:
+mkdir -p ~/.config/nix && echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
+```
+
+#### Activating the Development Environment
+
+```bash
+# Automatic activation with direnv (recommended)
+direnv allow
+
+# Or manual activation
+nix develop
+```
+
+The Nix development environment includes:
+
+- Python with uv package manager
+- Automatic dependency installation
+- Git hooks (treefmt + ty) auto-configured
+- Consistent environment across all platforms
 
 ## License