From a5ee39665e615a6bd1d8a3bffa06c28654a1f649 Mon Sep 17 00:00:00 2001
From: idrojone <jordivallspladaw@gmail.com>
Date: Sun, 26 Apr 2026 21:59:31 +0200
Subject: [PATCH] docs: clarify install-from-source versioning and Claude Code
 requirement

- Updated README.md and INSTALLATION.md to explain go build vs go install versioning.
- Added minimum Claude Code CLI version (>= 2.1.70) to AGENT-SETUP.md.

Closes #67
---
 .env                 | 12 ++++++++++++
 README.md            |  3 +++
 docs/AGENT-SETUP.md  |  4 +++-
 docs/INSTALLATION.md | 23 +++++++++++++++++------
 4 files changed, 35 insertions(+), 7 deletions(-)
 create mode 100644 .env

diff --git a/.env b/.env
new file mode 100644
index 00000000..b3feca45
--- /dev/null
+++ b/.env
@@ -0,0 +1,12 @@
+ENGRAM_DATABASE_URL="postgres://engram:engram_dev@postgres:5432/engram_cloud?sslmode=disable"
+ENGRAM_CLOUD_ALLOWED_PROJECTS="engram,policourt,go"
+ENGRAM_CLOUD_TOKEN="blostecito"
+ENGRAM_JWT_SECRET="blostecitoblostecitoblostecitoblostecitoblostecito"
+ENGRAM_CLOUD_HOST="0.0.0.0"
+ENGRAM_PORT="18080"
+ENGRAM_CLOUD_ADMIN="my-awesome-blostecito"
+
+POSTGRES_USER=engram
+POSTGRES_PASSWORD=engram_dev
+POSTGRES_DB=engram_cloud
+POSTGRES_IMAGE=postgres:16-alpine
\ No newline at end of file
diff --git a/README.md b/README.md
index c26d4d13..b5d822c5 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,9 @@ brew install gentleman-programming/tap/engram
 
 Windows, Linux, and other install methods → [docs/INSTALLATION.md](docs/INSTALLATION.md)
 
+> [!TIP]
+> Installing from source via `go build`? Use `-ldflags` to set the version string, or it will show as `"dev"`. See [Installation Guide](docs/INSTALLATION.md#install-from-source-macos--linux).
+
 ### Setup Your Agent
 
 | Agent | One-liner |
diff --git a/docs/AGENT-SETUP.md b/docs/AGENT-SETUP.md
index 4cb81540..b42ad1ac 100644
--- a/docs/AGENT-SETUP.md
+++ b/docs/AGENT-SETUP.md
@@ -89,7 +89,9 @@ claude plugin marketplace add Gentleman-Programming/engram
 claude plugin install engram
 ```
 
-That's it. The plugin registers the MCP server, hooks, and Memory Protocol skill automatically.
+> [!IMPORTANT]
+> **Minimum Claude Code version:** Marketplace installation requires Claude Code CLI **>= 2.1.70**.
+> If you see `Failed to add marketplace: Invalid schema: plugins.0.source`, please update with `claude update`.
 
 **Option B: Plugin via `engram setup`** — same plugin, installed from the embedded binary:
 
diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md
index 5c3715ae..a0913b9d 100644
--- a/docs/INSTALLATION.md
+++ b/docs/INSTALLATION.md
@@ -44,19 +44,25 @@ go install github.com/Gentleman-Programming/engram/cmd/engram@latest
 
 Ensure `%GOPATH%\bin` (or `%USERPROFILE%\go\bin`) is on your `PATH`.
 
-**Option B: Build from source**
+**Option B: Build from source (with version stamp)**
+
+If you want the exact version string in `engram version`, build it manually:
 
 ```powershell
 git clone https://github.com/Gentleman-Programming/engram.git
 cd engram
-go install ./cmd/engram
-# Binary goes to %GOPATH%\bin\engram.exe (typically %USERPROFILE%\go\bin\)
 
-# Optional: build with version stamp (otherwise `engram version` shows "dev")
+# 1. Compile with version stamp
 $v = git describe --tags --always
 go build -ldflags="-X main.version=local-$v" -o engram.exe ./cmd/engram
+
+# 2. Move to a folder in your PATH
+# (e.g. C:\Users\<you>\bin\ or similar)
 ```
 
+> [!NOTE]
+> Running `go install ./cmd/engram` puts the binary in `%GOPATH%\bin` (usually `%USERPROFILE%\go\bin\`) but sets the version to `"dev"`. To get the proper version string, you must use `go build` with `-ldflags` as shown above.
+
 **Option C: Download the prebuilt binary**
 
 1. Go to [GitHub Releases](https://github.com/Gentleman-Programming/engram/releases)
@@ -103,12 +109,17 @@ Expand-Archive engram_*_windows_amd64.zip -DestinationPath "$env:USERPROFILE\bin
 ```bash
 git clone https://github.com/Gentleman-Programming/engram.git
 cd engram
-go install ./cmd/engram
 
-# Optional: build with version stamp (otherwise `engram version` shows "dev")
+# Build with version stamp
 go build -ldflags="-X main.version=local-$(git describe --tags --always)" -o engram ./cmd/engram
+
+# Move to your PATH (e.g. /usr/local/bin or ~/bin)
+sudo mv engram /usr/local/bin/
 ```
 
+> [!NOTE]
+> Running `go install ./cmd/engram` puts the binary in `$GOPATH/bin` (usually `~/go/bin/`) but sets the version to `"dev"`. To get the proper version string, you must use `go build` with `-ldflags` as shown above.
+
 ---
 
 ## Download binary (all platforms)