fix: regenerate lavamoat policy from production dependencies

The lavamoat policy was generated against dev node_modules, but both
Docker and the recommended production setup use production-only
dependencies. This caused runtime policy violations because:

1. Shared transitive packages resolve through different parent chains
   in dev vs production node_modules.
2. config.js is loaded dynamically via a computed require() in
   settings.js, so lavamoat never discovers yargs and its deps.

Regenerated the policy from production dependencies using a shim that
statically requires config.js so lavamoat discovers the full dependency
graph. Added README instructions for running from source with
production deps to match the policy.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: andreabadesso

Makefile

@@ -89,3 +89,8 @@ xpub_from_seed: .script-build-dirs .run_xpub_from_seed .script-clean-dirs
 # Command: Derive multisig xPub from seed
 .PHONY: multisig_xpub_from_seed
 multisig_xpub_from_seed: .script-build-dirs .run_multisig_xpub_from_seed .script-clean-dirs
+
+# Command: Regenerate LavaMoat policy from production dependencies
+.PHONY: lavamoat_policy
+lavamoat_policy:
+	bash scripts/generate-lavamoat-policy.sh

README.md

@@ -12,6 +12,78 @@ A **headless wallet** is a wallet application whose interface is an API.
 
 To know how to operate and use Hathor headless wallet, see [Hathor headless wallet at Hathor docs — official technical documentation of Hathor](https://docs.hathor.network/pathways/components/headless-wallet).
 
+### Running with Docker
+
+The easiest way to run the headless wallet is with Docker. Pre-built images are available on [Docker Hub](https://hub.docker.com/r/hathornetwork/hathor-wallet-headless):
+
+```bash
+docker run -p 8000:8000 --env-file .env.headless hathornetwork/hathor-wallet-headless
+```
+
+Where `.env.headless` contains your configuration (do not commit this file):
+
+```
+HEADLESS_NETWORK=mainnet
+HEADLESS_SERVER=https://node1.mainnet.hathor.network/v1a/
+HEADLESS_SEED_DEFAULT=your seed words here
+HEADLESS_API_KEY=your_api_key
+```
+
+### Running from source
+
+Requirements: Node.js >= 22.0.0, npm >= 10.0.0.
+
+```bash
+# Install all dependencies (needed for the build step)
+npm ci
+
+# Copy and edit the configuration file
+cp config.js.template config.js
+# Edit config.js with your settings (seed, network, server, etc.)
+
+# Build the project
+npm run build
+
+# Remove dev dependencies so the runtime matches the LavaMoat policy
+rm -rf node_modules
+npm ci --only=production
+
+# Run
+npm run start:lavamoat
+```
+
+> **Note:** The [LavaMoat](https://github.com/LavaMoat/LavaMoat) security policy is generated against production dependencies. Dev dependencies change the dependency resolution paths, causing policy violations at runtime. That's why dev dependencies must be removed after building.
+
+### Development
+
+For local development without LavaMoat:
+
+```bash
+npm ci
+cp config.js.template config.js
+# Edit config.js with your settings
+
+# Run without LavaMoat (uses nodemon for auto-reload)
+npm run dev
+
+# Or build and run without LavaMoat
+npm run start
+```
+
+To test with LavaMoat locally, follow the [Running from source](#running-from-source) steps above.
+
+### Regenerating the LavaMoat policy
+
+When dependencies change, the LavaMoat policy must be regenerated. **Do not use `npm run lavamoat:policy`** — it generates the policy against dev dependencies, which won't work at runtime.
+
+Instead, use the provided script that generates the policy against production dependencies inside Docker:
+
+```bash
+make lavamoat_policy
+```
+
+This requires Docker to be running. The script builds the project with the Docker config, spins up a container with production-only `node_modules`, and runs `lavamoat --autopolicy` inside it.
+
 ## Support
 
 If after consulting the documentation, you still need **help to operate and use Hathor headless wallet**, [send a message to the `#development` channel on Hathor Discord server for assistance from Hathor team and community members](https://discord.com/channels/566500848570466316/663785995082268713).