Skip to content

docs: clarify install-from-source version stamp and Claude Code schema fallback#410

Merged
Alan-TheGentleman merged 1 commit into
Gentleman-Programming:mainfrom
carlosmoradev:docs/install-source-version-stamp
May 27, 2026
Merged

docs: clarify install-from-source version stamp and Claude Code schema fallback#410
Alan-TheGentleman merged 1 commit into
Gentleman-Programming:mainfrom
carlosmoradev:docs/install-source-version-stamp

Conversation

@carlosmoradev
Copy link
Copy Markdown
Contributor

🔗 Linked Issue

Closes #67


🏷️ PR Type

  • type:docs — Documentation only

📝 Summary

  • Rewrites the version-stamp tip in docs/INSTALLATION.md (Windows and macOS/Linux) so it is no longer two consecutive commands that leave the user with two binaries and engram version still printing dev. The new tip presents two explicit, mutually exclusive options.
  • Adds a focused troubleshooting callout in docs/AGENT-SETUP.md for the Claude Code marketplace schema error, pointing at claude update and naming Bare MCP as the fallback.

📂 Changes

File Change
docs/INSTALLATION.md Replaces the inline "Optional: build with version stamp" block in both Windows and macOS/Linux sections with a callout that shows Option 1 (go install -ldflags) and Option 2 (go build + move) as separate alternatives. Warns the reader not to run both.
docs/AGENT-SETUP.md Adds an "If the marketplace command fails with a schema error" callout right under the marketplace command in the Claude Code section.

🧪 Test Plan

  • Unit tests pass locally: go test ./... (no code changes; ran as a sanity check)
  • E2E tests pass locally: go test -tags e2e ./internal/server/... (no code changes; ran as a sanity check)
  • Manually verified that go install -ldflags="-X main.version=local-$(git describe --tags --always)" ./cmd/engram produces a binary whose engram version reports the stamped value instead of dev. The new instructions match observed behavior.

✅ Contributor Checklist

  • Linked an approved issue (Closes #67)
  • Added exactly one type:* label (type:docs)
  • Ran unit tests locally
  • Ran e2e tests locally
  • Docs updated (this PR is the doc update)
  • Commit follows conventional commits format
  • No Co-Authored-By trailers

💬 Notes for Reviewers

  • The current .claude-plugin/marketplace.json uses "source": "./plugin/claude-code", not "source": "git-subdir", so the exact failure mode the issue cites is not reproducible against main today. I kept the troubleshooting callout intentionally generic ("schema errors on some manifest fields") and named the Invalid schema: plugins.0.source: Invalid input text only as one example, so the guidance still helps users on older CLIs who hit any related schema issue (including any future change to the manifest).
  • I deliberately did NOT invent a "minimum Claude Code version" number. The original issue admitted the exact minimum was not precisely known, so the callout points at claude update (which always upgrades to the latest) instead of a specific version that might be wrong.
  • Both INSTALLATION.md blocks already had a one-line version-stamp tip. The rewrite preserves the same intent but resolves the PATH gotcha the issue described.

Two install-time confusions that Gentleman-Programming#67 surfaced:

1. The previous version-stamp tip suggested running both 'go install' AND
   'go build -o engram[.exe]' back-to-back. The build output goes to the
   current directory, not PATH, so 'engram version' keeps reporting 'dev'
   from the earlier 'go install'. Rewrites the tip as two explicit
   alternatives (-ldflags on go install, or build + move onto PATH), with
   a warning that they are mutually exclusive.

2. Older Claude Code CLI versions reject 'claude plugin marketplace add'
   with schema errors on some manifest fields ('Invalid schema:
   plugins.0.source: Invalid input'). Adds a focused troubleshooting
   callout right under the marketplace command pointing at 'claude update'
   and Option C (Bare MCP) as the fallback for users who cannot upgrade.

Verified locally that 'go install -ldflags=...' actually stamps the
version (engram version prints local-<describe>) so the new instructions
work as written.

Closes Gentleman-Programming#67
@carlosmoradev
Copy link
Copy Markdown
Contributor Author

Heads up: I do not have permission to add labels on this repo, so type:docs is missing. Whenever a maintainer can add it, the "Check PR Has type:* Label" gate will pass.

Copy link
Copy Markdown
Collaborator

@Alan-TheGentleman Alan-TheGentleman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the docs diff. The schema-error troubleshooting and the version-stamp clarification (B1 vs B2, avoiding the double binary on PATH) are accurate and match the actual go install behavior. Approving.

@Alan-TheGentleman Alan-TheGentleman merged commit 98f4e1d into Gentleman-Programming:main May 27, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type:docs Documentation only

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: clarify install-from-source version stamp and Claude Code CLI minimum version

2 participants