From 584adc0e21d9af3bb9d7797ce8169e2cda95255b Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <codeforester@gmail.com>
Date: Fri, 29 May 2026 04:17:06 -0700
Subject: [PATCH] Document mise guidance for Go and Java projects

---
 CHANGELOG.md            |  1 +
 README.md               | 35 +++++++++++++++++++++++++++++++++++
 docs/architecture.md    |  5 +++++
 docs/tool-boundaries.md |  3 +++
 4 files changed, 44 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c9a9d24..ebcaaff 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and Base versions are tracked in the repo-root `VERSION` file.
 
 ### Added
 
+- Added documentation guidance for using `mise` with Go and Java projects.
 - Added a repo-owned `bin/base-test` runner and declared it through
   `base_manifest.yaml` so Base can dogfood `basectl test base`.
 - Added GitHub CLI authentication diagnostics to developer prerequisite checks.
diff --git a/README.md b/README.md
index caf2ef7..d6ef992 100644
--- a/README.md
+++ b/README.md
@@ -171,6 +171,41 @@ test:
   mise: test
 ```
 
+For a polyglot project such as `banyanlabs`, keep Base at the workspace
+orchestration layer and let the language-native tools own their usual files.
+Base should see a small manifest contract:
+
+```yaml
+project:
+  name: banyanlabs
+
+brewfile: Brewfile
+
+mise: .mise.toml
+
+test:
+  mise: test
+```
+
+Then `.mise.toml` can pin the project runtimes and expose the task Base should
+delegate to:
+
+```toml
+[tools]
+go = "1.22"
+java = "temurin-21"
+
+[tasks.test]
+run = "go test ./... && ./gradlew test"
+```
+
+Use the `Brewfile` for ordinary workstation tools such as Maven, Gradle,
+`golangci-lint`, `protobuf`, or Docker-related CLIs when Homebrew is the right
+installer. Keep Go dependencies in `go.mod`/`go.sum` and Java dependencies in
+Maven or Gradle project files. Base does not need first-class `go-package` or
+`java-package` artifact types until it has a Base-specific behavior to add on
+top of those native ecosystems.
+
 Base should not run arbitrary setup hooks until there is an explicit,
 reviewable contract for when they run, where they run, whether they are
 interactive, and how dry-run/check/doctor report them.
diff --git a/docs/architecture.md b/docs/architecture.md
index c11b931..84dce1d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -347,6 +347,11 @@ orchestration actions. The design rule is delegation-first:
 - Use `mise` for tool versions, language runtimes, environment variables, and
   future tasks when a project opts into it. Base runs `mise install` during
   setup and does not reimplement mise's version management.
+- For Go and Java projects, put runtime pins such as `go = "1.22"` and
+  `java = "temurin-21"` in `.mise.toml`. Keep system tools in `Brewfile`, Go
+  dependencies in `go.mod`/`go.sum`, and Java dependencies in Maven or Gradle
+  project files. Base should orchestrate those contracts rather than add
+  generic language package artifact types.
 - Use a project-owned `test` contract for `basectl test <project>` delegation.
   Projects can declare either `test.command` for a shell command or `test.mise`
   for a `mise run <task>` delegation. Extra arguments after `basectl test
diff --git a/docs/tool-boundaries.md b/docs/tool-boundaries.md
index 821f5a9..001d13c 100644
--- a/docs/tool-boundaries.md
+++ b/docs/tool-boundaries.md
@@ -79,6 +79,9 @@ How Base should coexist:
 - allow a Base-managed project to declare that it uses `mise.toml`
 - let `basectl setup` or `basectl check` invoke `mise install`, `mise doctor`, or
   `mise run ...` when that is the project's chosen substrate
+- support Go, Java, and other language runtimes through project-owned
+  `.mise.toml` files instead of adding Base-owned package types for each
+  language ecosystem
 - keep Base at the workspace-orchestration layer, not the per-language tool
   installation layer