Refactor and improve documentation, add examples

docs/recipes/README.md

@@ -0,0 +1,20 @@
+# Recipes
+
+These are "cookbook" guides for common workflows. Most follow the same loop:
+
+1. Start with a restrictive config
+2. Run with monitor mode (`-m`) to see what gets blocked
+3. Allow the minimum domains/paths needed
+
+## Package installs
+
+- [npm install](npm-install.md)
+- [pip / poetry](pip-poetry.md)
+
+## Git / fetching code
+
+- [git clone / git fetch](git-clone.md)
+
+## CI
+
+- [CI jobs](ci.md)

docs/recipes/ci.md

@@ -0,0 +1,36 @@
+# Recipe: CI jobs
+
+Goal: make CI steps safer by default: minimal egress and controlled writes.
+
+## Suggested baseline
+
+```json
+{
+  "network": {
+    "allowedDomains": []
+  },
+  "filesystem": {
+    "allowWrite": [".", "/tmp"]
+  }
+}
+```
+
+Run:
+
+```bash
+fence --settings ./fence.json -c "make test"
+```
+
+## Add only what you need
+
+Use monitor mode to discover what a job tries to reach:
+
+```bash
+fence -m --settings ./fence.json -c "make test"
+```
+
+Then allowlist only:
+
+- your artifact/cache endpoints
+- the minimum package registries required
+- any internal services the job must access

docs/recipes/git-clone.md

@@ -0,0 +1,32 @@
+# Recipe: `git clone` / `git fetch`
+
+Goal: allow fetching code from a limited set of hosts.
+
+## HTTPS clone (GitHub example)
+
+```json
+{
+  "network": {
+    "allowedDomains": ["github.com", "api.github.com", "codeload.github.com"]
+  },
+  "filesystem": {
+    "allowWrite": ["."]
+  }
+}
+```
+
+Run:
+
+```bash
+fence --settings ./fence.json git clone https://github.com/OWNER/REPO.git
+```
+
+## SSH clone
+
+SSH traffic may go through SOCKS5 (`ALL_PROXY`) depending on your git/ssh configuration.
+
+If it fails, use monitor/debug mode to see what was blocked:
+
+```bash
+fence -m --settings ./fence.json git clone git@github.com:OWNER/REPO.git
+```

docs/recipes/npm-install.md

@@ -0,0 +1,37 @@
+# Recipe: `npm install`
+
+Goal: allow npm to fetch packages, but block unexpected egress.
+
+## Start restrictive
+
+```json
+{
+  "network": {
+    "allowedDomains": ["registry.npmjs.org", "*.npmjs.org"]
+  },
+  "filesystem": {
+    "allowWrite": [".", "node_modules", "/tmp"]
+  }
+}
+```
+
+Run:
+
+```bash
+fence --settings ./fence.json npm install
+```
+
+## Iterate with monitor mode
+
+If installs fail, run:
+
+```bash
+fence -m --settings ./fence.json npm install
+```
+
+Then add the minimum extra domains required for your workflow (private registries, GitHub tarballs, etc.).
+
+Notes:
+
+- If your dependencies fetch binaries during install, you may need to allow additional domains.
+- Keep allowlists narrow; prefer specific hostnames over broad wildcards.

docs/recipes/pip-poetry.md

@@ -0,0 +1,36 @@
+# Recipe: `pip` / `poetry`
+
+Goal: allow Python dependency fetching while keeping egress minimal.
+
+## Start restrictive (PyPI)
+
+```json
+{
+  "network": {
+    "allowedDomains": ["pypi.org", "files.pythonhosted.org"]
+  },
+  "filesystem": {
+    "allowWrite": [".", "/tmp"]
+  }
+}
+```
+
+Run:
+
+```bash
+fence --settings ./fence.json pip install -r requirements.txt
+```
+
+For Poetry:
+
+```bash
+fence --settings ./fence.json poetry install
+```
+
+## Iterate with monitor mode
+
+```bash
+fence -m --settings ./fence.json poetry install
+```
+
+If you use private indexes, add those domains explicitly.