diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
index a4d795a..420dda0 100644
--- a/.github/workflows/go.yml
+++ b/.github/workflows/go.yml
@@ -12,7 +12,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v4
         with:
-          go-version: "1.24"
+          go-version: "1.23"
       - name: Build
         run: make
       - name: Run tests with coverage
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7bc33b6..b4b6ff8 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -40,6 +40,21 @@ jobs:
           GOOS=linux GOARCH=386 go build -o sif-linux-386 ./cmd/sif
           GOOS=linux GOARCH=arm64 go build -o sif-linux-arm64 ./cmd/sif
 
+      - name: Package releases with modules
+        run: |
+          for binary in sif-linux-amd64 sif-linux-386 sif-linux-arm64 sif-macos-amd64 sif-macos-arm64; do
+            mkdir -p "dist/${binary}"
+            cp "${binary}" "dist/${binary}/sif"
+            cp -r modules "dist/${binary}/"
+            tar -czf "${binary}.tar.gz" -C dist "${binary}"
+          done
+          for binary in sif-windows-amd64 sif-windows-386; do
+            mkdir -p "dist/${binary}"
+            cp "${binary}.exe" "dist/${binary}/sif.exe"
+            cp -r modules "dist/${binary}/"
+            cd dist && zip -r "../${binary}.zip" "${binary}" && cd ..
+          done
+
       - name: Set release version
         run: echo "RELEASE_VERSION=$(git rev-parse --short HEAD)" >> $GITHUB_ENV
 
@@ -52,24 +67,35 @@ jobs:
             Automated release v${{ env.RELEASE_VERSION }}
 
             ## Assets
-            - Windows (64-bit): `sif-windows-amd64.exe`
-            - Windows (32-bit): `sif-windows-386.exe`
-            - macOS (64-bit Intel): `sif-macos-amd64`
-            - macOS (64-bit ARM): `sif-macos-arm64`
-            - Linux (64-bit): `sif-linux-amd64`
-            - Linux (32-bit): `sif-linux-386`
-            - Linux (64-bit ARM): `sif-linux-arm64`
+
+            Each archive contains the sif binary and built-in modules.
+
+            - Windows (64-bit): `sif-windows-amd64.zip`
+            - Windows (32-bit): `sif-windows-386.zip`
+            - macOS (64-bit Intel): `sif-macos-amd64.tar.gz`
+            - macOS (64-bit ARM): `sif-macos-arm64.tar.gz`
+            - Linux (64-bit): `sif-linux-amd64.tar.gz`
+            - Linux (32-bit): `sif-linux-386.tar.gz`
+            - Linux (64-bit ARM): `sif-linux-arm64.tar.gz`
+
+            ## Installation
+
+            ```bash
+            tar -xzf sif-linux-amd64.tar.gz
+            cd sif-linux-amd64
+            ./sif -h
+            ```
 
             For more details, check the [commit history](https://github.com/${{ github.repository }}/commits/main).
           draft: false
           prerelease: false
           files: |
-            sif-windows-amd64.exe
-            sif-windows-386.exe
-            sif-macos-amd64
-            sif-macos-arm64
-            sif-linux-amd64
-            sif-linux-386
-            sif-linux-arm64
+            sif-windows-amd64.zip
+            sif-windows-386.zip
+            sif-macos-amd64.tar.gz
+            sif-macos-arm64.tar.gz
+            sif-linux-amd64.tar.gz
+            sif-linux-386.tar.gz
+            sif-linux-arm64.tar.gz
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/runtest.yml b/.github/workflows/runtest.yml
index f33279d..370a6c7 100644
--- a/.github/workflows/runtest.yml
+++ b/.github/workflows/runtest.yml
@@ -27,3 +27,16 @@ jobs:
             echo "Sif exited with an error"
             exit 1
           fi
+
+      - name: Test module system
+        run: |
+          echo "Listing modules..."
+          ./sif -lm
+          echo "Running all modules..."
+          ./sif -u https://example.com -am
+          if [ $? -eq 0 ]; then
+            echo "Module system working"
+          else
+            echo "Module system failed"
+            exit 1
+          fi
diff --git a/README.md b/README.md
index c40f1a9..8c4e757 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
 [![license](https://img.shields.io/badge/license-BSD--3--Clause-blue?style=flat-square)](LICENSE)
 [![discord](https://img.shields.io/badge/discord-join-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/sifcli)
 
-**[install](#install) · [usage](#usage) · [modules](#modules) · [contribute](#contribute)**
+**[install](#install) · [usage](#usage) · [modules](#modules) · [docs](docs/) · [contribute](#contribute)**
 
 </div>
 
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..918dce0
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,52 @@
+# sif documentation
+
+welcome to the sif documentation. sif is a modular pentesting toolkit designed to be fast, concurrent, and extensible.
+
+## table of contents
+
+### getting started
+
+- [installation](installation.md) - how to install sif
+- [quickstart](quickstart.md) - get up and running in minutes
+- [usage](usage.md) - command line options and examples
+
+### features
+
+- [scans](scans.md) - built-in security scans
+- [modules](modules.md) - yaml module system and custom modules
+
+### reference
+
+- [configuration](configuration.md) - runtime configuration options
+- [api mode](api-mode.md) - json output for automation
+
+### contributing
+
+- [development](development.md) - setting up a dev environment
+- [writing modules](modules.md#writing-modules) - create your own modules
+
+---
+
+## quick links
+
+```bash
+# install
+git clone https://github.com/dropalldatabases/sif.git && cd sif && make
+
+# basic scan
+./sif -u https://example.com
+
+# list modules
+./sif -lm
+
+# run all modules
+./sif -u https://example.com -am
+
+# help
+./sif -h
+```
+
+## support
+
+- [github issues](https://github.com/vmfunc/sif/issues) - bug reports and feature requests
+- [discord](https://discord.gg/sifcli) - community chat
diff --git a/docs/api-mode.md b/docs/api-mode.md
new file mode 100644
index 0000000..c0662e1
--- /dev/null
+++ b/docs/api-mode.md
@@ -0,0 +1,160 @@
+# api mode
+
+use sif's json output for automation and integration.
+
+## enabling api mode
+
+```bash
+./sif -u https://example.com -api
+```
+
+## output format
+
+api mode outputs json to stdout:
+
+```json
+{
+  "url": "https://example.com",
+  "results": [
+    {
+      "id": "module-id",
+      "data": {
+        "module_id": "module-id",
+        "target": "https://example.com",
+        "findings": [
+          {
+            "url": "https://example.com/.git/HEAD",
+            "severity": "high",
+            "evidence": "ref: refs/heads/main",
+            "extracted": {
+              "branch": "main"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## fields
+
+### url
+
+the target url that was scanned.
+
+### results
+
+array of module results.
+
+### results[].id
+
+module identifier.
+
+### results[].data.findings
+
+array of security findings from the module.
+
+### findings[].url
+
+the specific url where the finding was detected.
+
+### findings[].severity
+
+severity level: `info`, `low`, `medium`, `high`, `critical`
+
+### findings[].evidence
+
+evidence that triggered the finding (matched content, etc).
+
+### findings[].extracted
+
+extracted data from the response (versions, keys, etc).
+
+## examples
+
+### save to file
+
+```bash
+./sif -u https://example.com -api -am > results.json
+```
+
+### pipe to jq
+
+```bash
+./sif -u https://example.com -api -am | jq '.results[].data.findings[]'
+```
+
+### filter high severity
+
+```bash
+./sif -u https://example.com -api -am | jq '.results[].data.findings[] | select(.severity == "high")'
+```
+
+### extract urls
+
+```bash
+./sif -u https://example.com -api -am | jq -r '.results[].data.findings[].url'
+```
+
+## ci/cd integration
+
+### github actions
+
+```yaml
+- name: run sif scan
+  run: |
+    ./sif -u ${{ env.TARGET_URL }} -api -am > sif-results.json
+
+- name: check for high severity findings
+  run: |
+    HIGH_COUNT=$(jq '[.results[].data.findings[] | select(.severity == "high" or .severity == "critical")] | length' sif-results.json)
+    if [ "$HIGH_COUNT" -gt 0 ]; then
+      echo "Found $HIGH_COUNT high/critical severity findings"
+      exit 1
+    fi
+```
+
+### gitlab ci
+
+```yaml
+security_scan:
+  script:
+    - ./sif -u $TARGET_URL -api -am > sif-results.json
+    - |
+      if jq -e '.results[].data.findings[] | select(.severity == "critical")' sif-results.json > /dev/null; then
+        echo "Critical findings detected"
+        exit 1
+      fi
+  artifacts:
+    paths:
+      - sif-results.json
+```
+
+## multiple targets
+
+when scanning multiple urls, each target outputs a separate json object:
+
+```bash
+./sif -u https://site1.com,https://site2.com -api
+```
+
+outputs:
+
+```json
+{"url":"https://site1.com","results":[...]}
+{"url":"https://site2.com","results":[...]}
+```
+
+use `jq -s` to combine into an array:
+
+```bash
+./sif -u https://site1.com,https://site2.com -api | jq -s '.'
+```
+
+## notes
+
+- api mode suppresses banner and interactive output
+- all output goes to stdout
+- errors and warnings still go to stderr
+- combine with `-l` flag to also save detailed logs
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..57eb643
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,162 @@
+# configuration
+
+runtime configuration options for sif.
+
+## environment variables
+
+### SHODAN_API_KEY
+
+required for shodan lookups.
+
+```bash
+export SHODAN_API_KEY=your-api-key-here
+./sif -u https://example.com -shodan
+```
+
+## command line options
+
+### timeout
+
+default request timeout is 10 seconds.
+
+```bash
+# increase for slow targets
+./sif -u https://example.com -t 30s
+
+# decrease for fast scans
+./sif -u https://example.com -t 5s
+```
+
+### threads
+
+default is 10 concurrent threads.
+
+```bash
+# more threads for faster scanning
+./sif -u https://example.com --threads 50
+
+# fewer threads to reduce load
+./sif -u https://example.com --threads 5
+```
+
+### logging
+
+save output to files:
+
+```bash
+./sif -u https://example.com -l ./logs
+```
+
+creates timestamped log files in the specified directory.
+
+### debug mode
+
+enable verbose logging:
+
+```bash
+./sif -u https://example.com -d
+```
+
+## user modules
+
+place custom modules in:
+
+- linux/macos: `~/.config/sif/modules/`
+- windows: `%LOCALAPPDATA%\sif\modules\`
+
+### directory structure
+
+```
+~/.config/sif/
+├── modules/
+│   ├── http/
+│   │   └── my-sqli-check.yaml
+│   ├── recon/
+│   │   └── custom-paths.yaml
+│   └── my-module.yaml
+```
+
+modules can be organized in subdirectories or placed directly in the modules folder.
+
+### overriding built-in modules
+
+user modules with the same id as built-in modules will override them:
+
+```yaml
+# ~/.config/sif/modules/sqli-error-based.yaml
+# this overrides the built-in sqli-error-based module
+
+id: sqli-error-based
+info:
+  name: my custom sqli check
+  # ...
+```
+
+## performance tuning
+
+### fast scans
+
+```bash
+./sif -u https://example.com \
+  --threads 50 \
+  -t 5s \
+  -dirlist small \
+  -dnslist small
+```
+
+### thorough scans
+
+```bash
+./sif -u https://example.com \
+  --threads 10 \
+  -t 30s \
+  -dirlist large \
+  -dnslist large \
+  -ports full
+```
+
+### low-impact scans
+
+reduce load on target:
+
+```bash
+./sif -u https://example.com \
+  --threads 2 \
+  -t 10s
+```
+
+## output formats
+
+### console (default)
+
+human-readable output with colors and formatting.
+
+### json (api mode)
+
+```bash
+./sif -u https://example.com -api
+```
+
+returns structured json:
+
+```json
+{
+  "url": "https://example.com",
+  "results": [
+    {
+      "id": "sqli-error-based",
+      "data": {
+        "findings": [...]
+      }
+    }
+  ]
+}
+```
+
+### log files
+
+```bash
+./sif -u https://example.com -l ./logs
+```
+
+creates separate log files for each scan type.
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..6c839f8
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,185 @@
+# development
+
+setting up a development environment for sif.
+
+## prerequisites
+
+- go 1.23 or later
+- git
+- make
+
+## clone and build
+
+```bash
+git clone https://github.com/dropalldatabases/sif.git
+cd sif
+make
+```
+
+## project structure
+
+```
+sif/
+├── cmd/sif/          # entry point
+│   └── main.go
+├── sif.go            # main application logic
+├── internal/         # private packages
+│   ├── config/       # configuration parsing
+│   ├── logger/       # logging utilities
+│   ├── modules/      # module system
+│   ├── scan/         # built-in scans
+│   ├── styles/       # terminal styling
+│   └── worker/       # worker pool
+├── modules/          # built-in yaml modules
+│   ├── http/         # http-based modules
+│   ├── info/         # information gathering
+│   └── recon/        # reconnaissance modules
+├── docs/             # documentation
+└── assets/           # images, etc
+```
+
+## running locally
+
+```bash
+# build
+make
+
+# run
+./sif -u https://example.com
+
+# run with debug
+./sif -u https://example.com -d
+```
+
+## code quality
+
+### format
+
+```bash
+gofmt -w .
+```
+
+### lint
+
+```bash
+golangci-lint run
+```
+
+### test
+
+```bash
+go test ./...
+```
+
+### race detection
+
+```bash
+go test -race ./...
+```
+
+## adding a new scan
+
+1. create a new file in `internal/scan/`
+2. implement the scan function
+3. add flag to `internal/config/config.go`
+4. integrate in `sif.go`
+
+see existing scans for examples.
+
+## adding a new module
+
+create a yaml file in `modules/`:
+
+```yaml
+id: my-new-module
+info:
+  name: my new security check
+  author: your-name
+  severity: medium
+  description: what this checks for
+  tags: [custom, security]
+
+type: http
+
+http:
+  method: GET
+  paths:
+    - "{{BaseURL}}/path"
+
+  matchers:
+    - type: status
+      status:
+        - 200
+```
+
+see [modules.md](modules.md) for the full format.
+
+## module system internals
+
+the module system is in `internal/modules/`:
+
+- `module.go` - core interface and types
+- `registry.go` - module registration
+- `loader.go` - discovery and loading
+- `yaml.go` - yaml parsing
+- `executor.go` - http execution
+
+### adding a new module type
+
+1. add type constant to `module.go`
+2. implement executor in new file
+3. update loader to handle new extension/type
+
+## testing
+
+### unit tests
+
+```bash
+go test ./internal/...
+```
+
+### functional test
+
+```bash
+./sif -u https://example.com -am
+```
+
+### test modules
+
+```bash
+./sif -lm  # list modules
+./sif -u https://example.com -m my-module -d  # test specific module
+```
+
+## pull requests
+
+1. fork the repository
+2. create a feature branch
+3. make changes
+4. run `gofmt -w .` and `golangci-lint run`
+5. submit pr
+
+### commit messages
+
+use lowercase, present tense:
+
+```
+add sql injection module
+fix timeout handling in http executor
+update readme with new flags
+```
+
+## release process
+
+releases are automated via github actions on push to main.
+
+binaries are built for:
+- linux (amd64, 386, arm64)
+- macos (amd64, arm64)
+- windows (amd64, 386)
+
+## resources
+
+- [go documentation](https://golang.org/doc/)
+- [goflags](https://github.com/projectdiscovery/goflags) - cli parsing
+- [nuclei templates](https://github.com/projectdiscovery/nuclei-templates) - module format inspiration
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..05165a1
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,93 @@
+# installation
+
+## from releases
+
+download the latest binary for your platform from [releases](https://github.com/vmfunc/sif/releases).
+
+### linux
+
+```bash
+# download
+curl -LO https://github.com/vmfunc/sif/releases/latest/download/sif-linux-amd64
+
+# make executable
+chmod +x sif-linux-amd64
+
+# move to path (optional)
+sudo mv sif-linux-amd64 /usr/local/bin/sif
+```
+
+### macos
+
+```bash
+# intel
+curl -LO https://github.com/vmfunc/sif/releases/latest/download/sif-macos-amd64
+
+# apple silicon
+curl -LO https://github.com/vmfunc/sif/releases/latest/download/sif-macos-arm64
+
+chmod +x sif-macos-*
+sudo mv sif-macos-* /usr/local/bin/sif
+```
+
+### windows
+
+download `sif-windows-amd64.exe` from releases and add to your PATH.
+
+## from source
+
+requires go 1.23+
+
+```bash
+git clone https://github.com/dropalldatabases/sif.git
+cd sif
+make
+```
+
+the binary will be created in the current directory.
+
+### install to system
+
+```bash
+sudo make install
+```
+
+this installs to `/usr/local/bin/sif`.
+
+### uninstall
+
+```bash
+sudo make uninstall
+```
+
+## verify installation
+
+```bash
+./sif -h
+```
+
+you should see the help output with available flags.
+
+## updating
+
+### from releases
+
+download the new binary and replace the old one.
+
+### from source
+
+```bash
+cd sif
+git pull
+make clean
+make
+```
+
+## modules directory
+
+sif looks for modules in these locations:
+
+- **built-in**: `modules/` directory next to the sif binary
+- **user modules**: `~/.config/sif/modules/` (linux/macos) or `%LOCALAPPDATA%\sif\modules\` (windows)
+
+user modules override built-in modules with the same id.
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 0000000..106f7d7
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,102 @@
+# quickstart
+
+get up and running with sif in minutes.
+
+## basic scan
+
+run a basic scan against a target:
+
+```bash
+./sif -u https://example.com
+```
+
+this performs a base scan checking robots.txt, common files, and basic reconnaissance.
+
+## add more scans
+
+enable additional scan types with flags:
+
+```bash
+# directory fuzzing
+./sif -u https://example.com -dirlist medium
+
+# subdomain enumeration
+./sif -u https://example.com -dnslist small
+
+# port scanning
+./sif -u https://example.com -ports common
+
+# framework detection
+./sif -u https://example.com -framework
+```
+
+## run modules
+
+sif has a modular architecture with yaml-based security checks:
+
+```bash
+# list available modules
+./sif -lm
+
+# run all modules
+./sif -u https://example.com -am
+
+# run specific modules
+./sif -u https://example.com -m sqli-error-based,xss-reflected
+
+# run by tag
+./sif -u https://example.com -mt owasp-top10
+```
+
+## multiple targets
+
+scan multiple urls:
+
+```bash
+./sif -u https://site1.com,https://site2.com
+```
+
+or from a file:
+
+```bash
+./sif -f targets.txt
+```
+
+## save output
+
+save results to a log directory:
+
+```bash
+./sif -u https://example.com -l ./logs
+```
+
+## json output
+
+for automation, use api mode:
+
+```bash
+./sif -u https://example.com -api
+```
+
+## full scan example
+
+run everything:
+
+```bash
+./sif -u https://example.com \
+  -dirlist medium \
+  -dnslist small \
+  -ports common \
+  -framework \
+  -js \
+  -headers \
+  -git \
+  -am \
+  -l ./logs
+```
+
+## next steps
+
+- [usage](usage.md) - all command line options
+- [scans](scans.md) - detailed scan descriptions
+- [modules](modules.md) - write custom modules
diff --git a/docs/scans.md b/docs/scans.md
new file mode 100644
index 0000000..08c5493
--- /dev/null
+++ b/docs/scans.md
@@ -0,0 +1,228 @@
+# scans
+
+detailed information about sif's built-in security scans.
+
+## base scan
+
+runs automatically unless `-noscan` is specified.
+
+checks:
+- robots.txt parsing
+- common files (sitemap.xml, security.txt, etc)
+- basic reconnaissance
+
+## directory fuzzing (-dirlist)
+
+brute-forces directories and files using wordlists.
+
+### sizes
+
+| size | entries | use case |
+|------|---------|----------|
+| small | ~1k | quick scan, low noise |
+| medium | ~10k | balanced coverage |
+| large | ~100k | thorough, takes longer |
+
+### what it finds
+
+- hidden directories (/admin, /backup, /config)
+- backup files (.bak, .old, .zip)
+- configuration files
+- development artifacts
+
+## subdomain enumeration (-dnslist)
+
+discovers subdomains via dns brute-forcing.
+
+### sizes
+
+| size | entries | use case |
+|------|---------|----------|
+| small | ~1k | quick discovery |
+| medium | ~10k | common subdomains |
+| large | ~100k | comprehensive |
+
+### what it finds
+
+- dev/staging environments
+- internal services
+- forgotten subdomains
+- api endpoints
+
+## port scanning (-ports)
+
+scans for open ports and identifies services.
+
+### scopes
+
+| scope | ports | description |
+|-------|-------|-------------|
+| common | top 1000 | most common services |
+| full | 1-65535 | all ports, slow |
+
+### what it finds
+
+- web servers (80, 443, 8080)
+- databases (3306, 5432, 27017)
+- admin interfaces (8443, 9090)
+- development servers
+
+## framework detection (-framework)
+
+identifies web frameworks and their versions.
+
+### detects
+
+- react, vue, angular, next.js
+- django, flask, rails
+- laravel, symfony, express
+- wordpress, drupal, joomla
+
+### features
+
+- version detection
+- cve lookup for known vulnerabilities
+- confidence scoring
+
+## javascript analysis (-js)
+
+analyzes javascript files for security issues.
+
+### finds
+
+- api endpoints and keys
+- hardcoded credentials
+- internal urls
+- framework configurations
+- source maps
+
+## http headers (-headers)
+
+analyzes security headers.
+
+### checks
+
+- content-security-policy
+- x-frame-options
+- x-content-type-options
+- strict-transport-security
+- x-xss-protection
+- permissions-policy
+
+## cms detection (-cms)
+
+identifies content management systems.
+
+### detects
+
+- wordpress (with version)
+- drupal
+- joomla
+- magento
+- shopify
+- ghost
+
+## git repository (-git)
+
+checks for exposed git repositories.
+
+### finds
+
+- .git/HEAD
+- .git/config
+- .git/index
+- source code exposure risk
+
+## cloud storage (-c3)
+
+checks for cloud storage misconfigurations.
+
+### checks
+
+- s3 bucket access
+- azure blob storage
+- gcp storage buckets
+- open bucket policies
+
+## subdomain takeover (-st)
+
+detects subdomain takeover vulnerabilities.
+
+requires `-dnslist` to enumerate subdomains first.
+
+### checks
+
+- dangling cname records
+- unclaimed cloud services
+- expired third-party services
+
+## shodan lookup (-shodan)
+
+queries shodan for host intelligence.
+
+requires `SHODAN_API_KEY` environment variable.
+
+### returns
+
+- open ports
+- services and versions
+- known vulnerabilities
+- ssl/tls info
+- organization data
+
+## sql reconnaissance (-sql)
+
+detects sql-related exposures.
+
+### finds
+
+- admin panels (/phpmyadmin, /adminer)
+- database error messages
+- sql injection indicators
+
+## lfi scanning (-lfi)
+
+checks for local file inclusion vulnerabilities.
+
+### tests
+
+- path traversal (../)
+- null byte injection
+- common lfi payloads
+- sensitive file disclosure
+
+## whois lookup (-whois)
+
+performs whois lookups on target domains.
+
+### returns
+
+- registrar info
+- creation/expiration dates
+- nameservers
+- registrant info (if available)
+
+## google dorking (-dork)
+
+automated google dorking for target.
+
+### searches
+
+- indexed sensitive files
+- exposed admin panels
+- configuration files
+- backup files
+- error pages
+
+## nuclei scanning (-nuclei)
+
+runs nuclei vulnerability templates.
+
+requires nuclei to be installed.
+
+### templates
+
+- cve detection
+- misconfigurations
+- exposures
+- default credentials
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000..cb5480c
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,293 @@
+# usage
+
+complete guide to sif command line options.
+
+## target options
+
+### -u, --urls
+
+specify target urls (comma-separated):
+
+```bash
+./sif -u https://example.com
+./sif -u https://site1.com,https://site2.com
+```
+
+### -f, --file
+
+read targets from a file (one url per line):
+
+```bash
+./sif -f targets.txt
+```
+
+## scan options
+
+### directory fuzzing
+
+`-dirlist <size>` - fuzz for directories and files
+
+sizes: `small`, `medium`, `large`
+
+```bash
+./sif -u https://example.com -dirlist medium
+```
+
+### subdomain enumeration
+
+`-dnslist <size>` - enumerate subdomains
+
+sizes: `small`, `medium`, `large`
+
+```bash
+./sif -u https://example.com -dnslist small
+```
+
+### port scanning
+
+`-ports <scope>` - scan for open ports
+
+scopes: `common` (top ports), `full` (all ports)
+
+```bash
+./sif -u https://example.com -ports common
+```
+
+### google dorking
+
+`-dork` - automated google dorking
+
+```bash
+./sif -u https://example.com -dork
+```
+
+### git repository detection
+
+`-git` - check for exposed git repositories
+
+```bash
+./sif -u https://example.com -git
+```
+
+### nuclei scanning
+
+`-nuclei` - run nuclei vulnerability templates
+
+```bash
+./sif -u https://example.com -nuclei
+```
+
+### javascript analysis
+
+`-js` - analyze javascript files
+
+```bash
+./sif -u https://example.com -js
+```
+
+### cms detection
+
+`-cms` - detect content management systems
+
+```bash
+./sif -u https://example.com -cms
+```
+
+### http headers
+
+`-headers` - analyze security headers
+
+```bash
+./sif -u https://example.com -headers
+```
+
+### cloud storage
+
+`-c3` - check for cloud storage misconfigurations
+
+```bash
+./sif -u https://example.com -c3
+```
+
+### subdomain takeover
+
+`-st` - check for subdomain takeover vulnerabilities
+
+requires `-dnslist` to be enabled
+
+```bash
+./sif -u https://example.com -dnslist small -st
+```
+
+### shodan lookup
+
+`-shodan` - query shodan for host intelligence
+
+requires `SHODAN_API_KEY` environment variable
+
+```bash
+export SHODAN_API_KEY=your-api-key
+./sif -u https://example.com -shodan
+```
+
+### sql reconnaissance
+
+`-sql` - detect sql admin panels and error disclosure
+
+```bash
+./sif -u https://example.com -sql
+```
+
+### lfi scanning
+
+`-lfi` - local file inclusion vulnerability checks
+
+```bash
+./sif -u https://example.com -lfi
+```
+
+### framework detection
+
+`-framework` - detect web frameworks with version and cve lookup
+
+```bash
+./sif -u https://example.com -framework
+```
+
+### whois lookup
+
+`-whois` - perform whois lookups
+
+```bash
+./sif -u https://example.com -whois
+```
+
+### skip base scan
+
+`-noscan` - skip the base url scan (robots.txt, etc)
+
+```bash
+./sif -u https://example.com -noscan -dirlist medium
+```
+
+## module options
+
+### -lm, --list-modules
+
+list all available modules:
+
+```bash
+./sif -lm
+```
+
+### -m, --modules
+
+run specific modules by id (comma-separated):
+
+```bash
+./sif -u https://example.com -m sqli-error-based,xss-reflected
+```
+
+### -mt, --module-tags
+
+run modules matching tags:
+
+```bash
+./sif -u https://example.com -mt owasp-top10
+./sif -u https://example.com -mt injection
+```
+
+### -am, --all-modules
+
+run all available modules:
+
+```bash
+./sif -u https://example.com -am
+```
+
+## runtime options
+
+### -t, --timeout
+
+http request timeout (default: 10s):
+
+```bash
+./sif -u https://example.com -t 30s
+```
+
+### --threads
+
+number of concurrent threads (default: 10):
+
+```bash
+./sif -u https://example.com --threads 20
+```
+
+### -l, --log
+
+directory to save log files:
+
+```bash
+./sif -u https://example.com -l ./logs
+```
+
+### -d, --debug
+
+enable debug logging:
+
+```bash
+./sif -u https://example.com -d
+```
+
+## api options
+
+### -api
+
+enable api mode for json output:
+
+```bash
+./sif -u https://example.com -api
+```
+
+output is a json object with scan results.
+
+## examples
+
+### quick recon
+
+```bash
+./sif -u https://example.com -framework -headers -git
+```
+
+### full scan
+
+```bash
+./sif -u https://example.com \
+  -dirlist large \
+  -dnslist medium \
+  -ports full \
+  -framework \
+  -js \
+  -headers \
+  -cms \
+  -git \
+  -sql \
+  -lfi \
+  -am
+```
+
+### ci/cd pipeline
+
+```bash
+./sif -u https://staging.example.com -api -am > results.json
+```
+
+### batch scanning
+
+```bash
+echo "https://site1.com
+https://site2.com
+https://site3.com" > targets.txt
+
+./sif -f targets.txt -am -l ./logs
+```