From 27f4bda16cdfbbd7c75789b4a43daedaf6d15d95 Mon Sep 17 00:00:00 2001
From: Beon de Nood <beon@bigdune.net>
Date: Sat, 2 May 2026 11:12:40 -0400
Subject: [PATCH] docs: fix binary install location documentation

Binary installs to <package>/bin/ first, with ~/.capiscio/bin as
fallback when package dir is read-only. Download is lazy (no
postinstall). Docs previously only documented the fallback path.

Fixes: DOCS_REMEDIATION_PLAN P2-9
---
 README.md                            | 9 +++++----
 docs/getting-started/installation.md | 7 ++++---
 docs/index.md                        | 4 ++--
 3 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 09da7df..8a8fe69 100644
--- a/README.md
+++ b/README.md
@@ -55,10 +55,11 @@ The Node.js wrapper includes specific commands to manage the binary:
 ## How It Works
 
 1. **Detection**: When you run `capiscio`, the script detects your OS (Linux, macOS, Windows) and Architecture (AMD64, ARM64).
-2. **Provisioning**: It checks if the correct `capiscio-core` binary is present in the cache.
-   - *Linux/macOS*: `~/.capiscio/bin`
-   - *Windows*: `%USERPROFILE%\.capiscio\bin`
-3. **Download**: If missing, it securely downloads the release from GitHub.
+2. **Provisioning**: It checks if the correct `capiscio-core` binary is present:
+   - **Primary**: `<package>/bin/capiscio` (alongside node_modules)
+   - **Fallback**: `~/.capiscio/bin/capiscio` (if package dir is read-only)
+   - *Windows fallback*: `%USERPROFILE%\.capiscio\bin`
+3. **Download**: If missing, it downloads the release from GitHub on first run (no postinstall script).
 4. **Execution**: It seamlessly delegates to the Go binary, passing all arguments through.
 
 ## Supported Platforms
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index b9230d8..6dff5c3 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -42,10 +42,11 @@ $ capiscio --version
 capiscio version 1.0.2
 ```
 
-The binary is cached in:
+The binary is stored in:
 
-- **macOS/Linux**: `~/.capiscio/bin/`
-- **Windows**: `%USERPROFILE%\.capiscio\bin\`
+- **Primary**: `<package>/bin/capiscio` (alongside node_modules)
+- **Fallback**: `~/.capiscio/bin/capiscio` (if package dir is read-only)
+- **Windows fallback**: `%USERPROFILE%\.capiscio\bin\`
 
 ## Environment Variables
 
diff --git a/docs/index.md b/docs/index.md
index ac09df8..d6f5d46 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -89,10 +89,10 @@ capiscio --version
 ## What This Package Does
 
 1. **Downloads** the correct `capiscio-core` binary for your platform (macOS/Linux/Windows, AMD64/ARM64)
-2. **Caches** the binary in `~/.capiscio/bin` (or `%USERPROFILE%\.capiscio\bin` on Windows)
+2. **Caches** the binary in `<package>/bin/` (primary) or `~/.capiscio/bin` (fallback if package dir is read-only)
 3. **Executes** the binary with your arguments via `execa` with inherited stdio
 
-All validation logic lives in `capiscio-core`. This wrapper just makes it easy to install via npm.
+All validation logic lives in `capiscio-core`. This wrapper just makes it easy to install via npm. No postinstall script runs — download happens lazily on first command.
 
 ## Wrapper-Specific Commands