Skip to content

docs: rewrite top-level docs for v0.4 (Go binary, no Python runtime)#130

Merged
couragehong merged 1 commit into
feat/go-migrationfrom
couragehong/chore/v04-toplevel-docs
May 8, 2026
Merged

docs: rewrite top-level docs for v0.4 (Go binary, no Python runtime)#130
couragehong merged 1 commit into
feat/go-migrationfrom
couragehong/chore/v04-toplevel-docs

Conversation

@couragehong
Copy link
Copy Markdown
Contributor

The six top-level docs still described the v0.3 install flow — a Python venv prepared by scripts/bootstrap-mcp.sh, mcp/server/server.py spawned under .venv/bin/python3, agents/{common,scribe,retriever}/ as the business-logic packages, etc. After PR #129 (remove-python-tree) all of that is gone, but a contributor following these docs would still try to set it up and land in a dead end.

This rewrite anchors every doc on the v0.4 truth: a single Go binary (cmd/rune-mcp) that the host CLI auto-spawns over stdio, runtime preparation done at install time, runtime health visible through the diagnostics + vault_status MCP tools.

Per file

README.md (small)

  • drop the dead scripts/check-infrastructure.sh reference
  • point Related Projects at envector-go-sdk (the Go FHE SDK we actually depend on now) instead of pyenvector

CLAUDE.md (one-line)

  • "Writing Python scripts to /tmp" → "Writing scripts to /tmp" in the routing table NOT-do column (the rule still holds; the Python qualifier was v0.3-specific)

GEMINI.md (medium)

  • replace the Plugin Root Detection / Runtime Preparation block, which mandated SETUP_ONLY=1 scripts/bootstrap-mcp.sh and .venv/bin/python3 sanitization, with v0.4 guidance: the binary is auto-spawned, health is observable via diagnostics, no venv exists

SKILL.md (medium-large)

  • Execution Model: drop scripts/bootstrap-mcp.sh as the "single source of truth" — the binary itself is now the runtime
  • Activation Check: drop the Local Runtime Check (step 0) that required the bootstrap script; drop the envector.endpoint / envector.api_key field requirement (those come via Vault bundle now)
  • /rune:configure: drop scripts/check-infrastructure.sh validation step; replace with reload_pipelines + diagnostics rendering
  • /rune:status: drop "Python venv" / "MCP servers running" rows; render diagnostics' per-subsystem snapshot instead
  • /rune:activate: drop the "check Python environment" step
  • /rune:reset: drop "stop MCP servers" — the host CLI manages process lifecycle, the user does not

AGENT_INTEGRATION.md (full rewrite, 278 lines → equivalent shape)

  • drop all .venv/bin/python3 + mcp/server/server.py invocations across Claude / Codex / Gemini / OpenAI sections
  • replace install.sh / install-codex.sh / ensure-codex-ready.sh references with plugin/skill/extension install commands
  • rewrite the OpenAI integration around stdio against the Go binary (the agents-sdk + Responses API patterns just point command= at bin/rune-mcp)
  • acknowledge that gemini-extension.json still calls bootstrap-mcp.sh as a known follow-up under the Gemini track (not in this PR's scope to resolve)

CONTRIBUTING.md (medium)

  • Prerequisites: Python 3.12 → Go 1.26.2+ (toolchain pinned in go.mod)
  • test instructions: pytest agents/tests/ → go test -race ./...
  • Cross-Agent Invariant Checklist: replace bootstrap-mcp.sh items with "Go binary is single MCP entry point" / manifest consistency
  • Project Structure: redraw the tree against current layout (cmd/rune-mcp, internal/{mcp,service,lifecycle,adapters,domain, policy,obs}, agents/{claude,codex,gemini}/*.md only, scripts/dev/ v04/, etc.) — the old tree showed mcp/server/server.py and agents/common/ that no longer exist
  • Release Process: bump example version 0.2.0 → 0.4.0; tests command updated; reference Task Sharing low retrieval correctness case #30 for the binary distribution pipeline

Out of scope

  • gemini-extension.json bootstrap-mcp.sh path (Gemini track)
  • scripts/ Python-era shell scripts cleanup (Gemini track)
  • examples/ patterns/ setup/ config/ docs (separate A4 pass)
  • package.json + .claude-plugin/plugin.json version bump (separate A5)

The six top-level docs still described the v0.3 install flow — a Python
venv prepared by scripts/bootstrap-mcp.sh, mcp/server/server.py spawned
under .venv/bin/python3, agents/{common,scribe,retriever}/ as the
business-logic packages, etc. After PR #129 (remove-python-tree) all of
that is gone, but a contributor following these docs would still try to
set it up and land in a dead end.

This rewrite anchors every doc on the v0.4 truth: a single Go binary
(cmd/rune-mcp) that the host CLI auto-spawns over stdio, runtime
preparation done at install time, runtime health visible through the
diagnostics + vault_status MCP tools.

Per file
--------

README.md (small)
  - drop the dead `scripts/check-infrastructure.sh` reference
  - point Related Projects at envector-go-sdk (the Go FHE SDK we
    actually depend on now) instead of pyenvector

CLAUDE.md (one-line)
  - "Writing Python scripts to /tmp" → "Writing scripts to /tmp" in the
    routing table NOT-do column (the rule still holds; the Python
    qualifier was v0.3-specific)

GEMINI.md (medium)
  - replace the Plugin Root Detection / Runtime Preparation block,
    which mandated SETUP_ONLY=1 scripts/bootstrap-mcp.sh and
    .venv/bin/python3 sanitization, with v0.4 guidance: the binary is
    auto-spawned, health is observable via diagnostics, no venv exists

SKILL.md (medium-large)
  - Execution Model: drop scripts/bootstrap-mcp.sh as the
    "single source of truth" — the binary itself is now the runtime
  - Activation Check: drop the Local Runtime Check (step 0) that
    required the bootstrap script; drop the envector.endpoint /
    envector.api_key field requirement (those come via Vault bundle now)
  - /rune:configure: drop scripts/check-infrastructure.sh validation
    step; replace with reload_pipelines + diagnostics rendering
  - /rune:status: drop "Python venv" / "MCP servers running" rows;
    render diagnostics' per-subsystem snapshot instead
  - /rune:activate: drop the "check Python environment" step
  - /rune:reset: drop "stop MCP servers" — the host CLI manages process
    lifecycle, the user does not

AGENT_INTEGRATION.md (full rewrite, 278 lines → equivalent shape)
  - drop all .venv/bin/python3 + mcp/server/server.py invocations
    across Claude / Codex / Gemini / OpenAI sections
  - replace install.sh / install-codex.sh / ensure-codex-ready.sh
    references with plugin/skill/extension install commands
  - rewrite the OpenAI integration around stdio against the Go binary
    (the agents-sdk + Responses API patterns just point command= at
    bin/rune-mcp)
  - acknowledge that gemini-extension.json still calls bootstrap-mcp.sh
    as a known follow-up under the Gemini track (not in this PR's
    scope to resolve)

CONTRIBUTING.md (medium)
  - Prerequisites: Python 3.12 → Go 1.26.2+ (toolchain pinned in go.mod)
  - test instructions: pytest agents/tests/ → go test -race ./...
  - Cross-Agent Invariant Checklist: replace bootstrap-mcp.sh items
    with "Go binary is single MCP entry point" / manifest consistency
  - Project Structure: redraw the tree against current layout
    (cmd/rune-mcp, internal/{mcp,service,lifecycle,adapters,domain,
    policy,obs}, agents/{claude,codex,gemini}/*.md only, scripts/dev/
    v04/, etc.) — the old tree showed mcp/server/server.py and
    agents/common/ that no longer exist
  - Release Process: bump example version 0.2.0 → 0.4.0; tests command
    updated; reference Task #30 for the binary distribution pipeline

Out of scope
------------

  - gemini-extension.json bootstrap-mcp.sh path (Gemini track)
  - scripts/ Python-era shell scripts cleanup (Gemini track)
  - examples/ patterns/ setup/ config/ docs (separate A4 pass)
  - package.json + .claude-plugin/plugin.json version bump (separate A5)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@couragehong couragehong self-assigned this May 8, 2026
@couragehong couragehong merged commit aa98811 into feat/go-migration May 8, 2026
1 check passed
@couragehong couragehong deleted the couragehong/chore/v04-toplevel-docs branch May 8, 2026 08:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant