fix(linux): prioritize native install path

Make the CLI self-contained without a missing local incubator workspace, switch the installer to a Linux-first native flow, and generate plugin lifecycle fixtures inside backend tests. Bump release metadata to v2.5.8-dev and update repo docs for the Linux-first path.

Author: FTMahringer

.github/release-notes/v2.5.8-dev.md

@@ -0,0 +1,23 @@
+# SYNAPSE v2.5.8-dev
+
+Linux stabilization starts here with Ubuntu 24.04 WSL2 as the primary target.
+
+## Highlights
+
+- CLI build no longer depends on the missing local `go-tui-incubator` workspace.
+- Installer flow now treats native Linux as the primary path and Docker Compose as optional.
+- Plugin lifecycle integration fixtures are generated inside backend tests instead of depending on a local ignored template checkout.
+- Root docs and onboarding references were cleaned up for Linux-first usage and repo-relative paths.
+
+## Scope
+
+- Backend
+- CLI
+- Plugin lifecycle test flow
+- Installer scripts
+- Main repo docs
+
+## Notes
+
+- Validation in the current workspace was limited because Go and Java were not installed/configured at release time.
+- The paired docs pre-release for this docs-affecting dev cycle is tracked in `Synapse-docs`.

.gitignore

@@ -1,10 +1,14 @@
 # Maven build output
 packages/core/target/
+synapse-plugin-api/target/
 
 # IDE
 .idea/
 .vscode/
 *.iml
+*.classpath
+*.project
+*.settings/
 
 # OS
 .DS_Store
@@ -16,9 +20,9 @@ Thumbs.db
 # Environment
 .env
 .env.local
-/synapse-docs
+/Synapse-docs
 /synapse-plugins
-/synapse-plugin-template
+/Synapse-plugin-template
 /synapse-plugins-community
 /.installer-tmp
 /go-tui-incubator

AGENT.md

@@ -24,7 +24,7 @@ Before major work:
 ## Repository context and boundaries
 
 - Main codebase root: this repository.
-- Docs live in nested, separate git repo: `synapse-docs\`.
+- Docs live in a nested, separate git repo when present: `synapse-docs/`.
 - Never mix commits across these repositories.
 - Keep changes scoped to the active task; avoid unrelated refactors.
 - Linux is the primary runtime target for validation work.
@@ -53,5 +53,5 @@ Before major work:
 
 - Project rules: `RULES.md`
 - Root changelog: `CHANGELOG.md`
-- Docs repository: `synapse-docs\`
-- Linux migration notes: `docs\NEXT_LINUX_PLAN.md`
+- Docs repository: `synapse-docs/`
+- Linux migration notes: `docs/NEXT_LINUX_PLAN.md`

AGENTS_QUICKSTART.md

@@ -2,16 +2,16 @@
 
 ## Read
 
-- [AGENT.md](/D:/projects/Agents-Umgeung-planning/Synapse/AGENT.md)
-- [RULES.md](/D:/projects/Agents-Umgeung-planning/Synapse/RULES.md)
-- [INSTRUCTIONS.md](/D:/projects/Agents-Umgeung-planning/Synapse/INSTRUCTIONS.md)
+- [AGENT.md](./AGENT.md)
+- [RULES.md](./RULES.md)
+- [INSTRUCTIONS.md](./INSTRUCTIONS.md)
 
 ## Work Areas
 
 - `packages/core`
 - `packages/cli`
 - `synapse-plugin-api`
-- `synapse-plugin-template`
+- `synapse-plugin-template` may be absent in a clean clone
 - `docs/roadmaps`
 - `docs/superpowers`
 

CHANGELOG.md

@@ -9,6 +9,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [v2.5.8-dev] - 2026-05-18
+
+**Linux Stabilization — Ubuntu 24.04 WSL2 First**
+
+### Fixed
+- CLI build no longer depends on the missing local `go-tui-incubator` workspace; it uses the in-repo terminal, theme, and output packages.
+- Plugin lifecycle integration fixtures are now generated inside backend tests instead of requiring an ignored local `synapse-plugin-template` checkout.
+- Installer prerequisites no longer force Docker for the base flow; native Linux setup remains valid even when Docker Compose is unavailable.
+
+### Changed
+- `install.sh` now defaults to the native Linux path and leaves Docker Compose as an explicit optional follow-up.
+- Root agent docs and quickstart references now use repo-relative paths instead of hardcoded Windows drive paths.
+- README quick start now recommends native Linux setup first and treats Docker Compose as optional.
+
+---
+
 ## [v2.5.7-dev] - 2026-05-12
 
 **Plugin Ecosystem — Official Plugin Library**

INSTRUCTIONS.md

@@ -4,21 +4,21 @@ Short handoff for other agents working in this repo.
 
 ## Read First
 
-- [AGENT.md](/D:/projects/Agents-Umgeung-planning/Synapse/AGENT.md)
-- [RULES.md](/D:/projects/Agents-Umgeung-planning/Synapse/RULES.md)
-- [README.md](/D:/projects/Agents-Umgeung-planning/Synapse/README.md)
-- [IDEAS.md](/D:/projects/Agents-Umgeung-planning/Synapse/IDEAS.md)
+- [AGENT.md](./AGENT.md)
+- [RULES.md](./RULES.md)
+- [README.md](./README.md)
+- [IDEAS.md](./IDEAS.md)
 
 ## Important Areas
 
-- [packages/core/pom.xml](/D:/projects/Agents-Umgeung-planning/Synapse/packages/core/pom.xml)
-- [packages/core/src/main/java/](/D:/projects/Agents-Umgeung-planning/Synapse/packages/core/src/main/java/)
-- [packages/core/src/test/java/](/D:/projects/Agents-Umgeung-planning/Synapse/packages/core/src/test/java/)
-- [packages/cli/](/D:/projects/Agents-Umgeung-planning/Synapse/packages/cli/)
-- [synapse-plugin-api/](/D:/projects/Agents-Umgeung-planning/Synapse/synapse-plugin-api/)
-- [synapse-plugin-template/](/D:/projects/Agents-Umgeung-planning/Synapse/synapse-plugin-template/)
-- [docs/roadmaps/](/D:/projects/Agents-Umgeung-planning/Synapse/docs/roadmaps/)
-- [docs/superpowers/](/D:/projects/Agents-Umgeung-planning/Synapse/docs/superpowers/)
+- [packages/core/pom.xml](./packages/core/pom.xml)
+- [packages/core/src/main/java/](./packages/core/src/main/java/)
+- [packages/core/src/test/java/](./packages/core/src/test/java/)
+- [packages/cli/](./packages/cli/)
+- [synapse-plugin-api/](./synapse-plugin-api/)
+- `synapse-plugin-template/` is optional local test scaffolding and may be absent in a clean Linux clone.
+- [docs/roadmaps/](./docs/roadmaps/)
+- [docs/superpowers/](./docs/superpowers/)
 
 ## Current Focus
 

README.md

@@ -29,16 +29,45 @@ SYNAPSE is a self-hosted, fully extensible AI platform that puts you in complete
 
 ### Prerequisites
 
-- **Docker & Docker Compose** (recommended) **or** local development tools:
+- Primary validation target: Ubuntu 24.04 on WSL2 or native Linux
+- Recommended native toolchain:
   - JDK 25+
   - Maven 3.9+
   - Node.js 22+
   - Go 1.26+
   - PostgreSQL 18+
   - Redis 8+
-- Supported OS: Linux, macOS, or Windows (WSL2 recommended)
+  - Qdrant 1.14+
+- Docker Compose is supported as an optional path, not the only install path.
 
-### Docker Compose Setup (Recommended)
+### Native Linux Setup (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/FTMahringer/Synapse.git
+cd Synapse
+
+# Bootstrap the CLI and generate local config
+./install.sh
+
+# Or prepare environment variables manually
+cp .env.example .env
+
+# Start local dependencies first, then run the backend
+cd packages/core
+mvn spring-boot:run
+
+# In another shell, run the dashboard
+cd packages/dashboard/frontend
+npm install
+npm run dev
+
+# In another shell, use the CLI
+cd packages/cli
+go run . health
+```
+
+### Docker Compose Setup (Optional)
 
 ```bash
 # Clone the repository
@@ -87,26 +116,7 @@ POSTGRES_PASSWORD=your-secure-password
 ECHO_ENABLED=false
 ```
 
-### Manual Development Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/FTMahringer/Synapse.git
-cd Synapse
-
-# Backend (requires PostgreSQL and Redis running)
-cd packages/core
-mvn spring-boot:run
-
-# Frontend
-cd packages/dashboard/frontend
-npm install
-npm run dev
-
-# CLI
-cd packages/cli
-go run main.go health
-```
+The native path is the first target for Linux stabilization. Use the Docker path when you specifically want containerized services.
 
 ---
 

install.sh

@@ -29,6 +29,10 @@ ok()    { printf "${GREEN}✓ %s${RESET}\n" "$1"; }
 warn()  { printf "${YELLOW}⚠ %s${RESET}\n" "$1"; }
 err()   { printf "${RED}✗ %s${RESET}\n" "$1"; }
 
+go_version_token() {
+  go version 2>/dev/null | awk '{print $3}'
+}
+
 # ── OS Detection ─────────────────────────────────────────────────
 detect_os() {
   case "$(uname -s)" in
@@ -101,7 +105,7 @@ install_go() {
   esac
 
   if command -v go &>/dev/null; then
-    ok "Go $(go version | grep -oP 'go\S+' || true) installed"
+    ok "Go $(go_version_token)" installed
   else
     err "Go installation failed. Please install manually: https://go.dev/dl/"
     exit 1
@@ -164,7 +168,7 @@ echo ""
 
 # Step 2: Check / Install Go
 if command -v go &>/dev/null; then
-  GO_VER=$(go version | grep -oP 'go\S+' || true)
+  GO_VER=$(go_version_token)
   ok "Go ${GO_VER} found"
 else
   warn "Go not found — installing..."
@@ -176,12 +180,13 @@ echo ""
 build_and_install
 
 # Step 4: Run the interactive TUI installer
-info "Launching interactive installer..."
+info "Launching interactive installer (native Linux path)..."
 echo ""
-"$BIN_DIR/synapse" install
+"$BIN_DIR/synapse" install --skip-docker
 
 echo ""
 ok "Installation complete!"
 ok "You can now use 'synapse' from any terminal."
 echo ""
 info "Run 'synapse --help' to see available commands."
+info "Run 'docker compose -f installer/compose/docker-compose.yml --env-file .env up -d' later if you want the optional container path."

packages/cli/cmd/agents.go

@@ -3,17 +3,16 @@ package cmd
 import (
 	"fmt"
 
-	tuioutput "github.com/FTMahringer/go-tui-incubator/output"
 	"github.com/spf13/cobra"
 	"github.com/synapse-dev/synapse-cli/internal/commandfeatures"
-	clioutput "github.com/synapse-dev/synapse-cli/internal/output"
+	tuioutput "github.com/synapse-dev/synapse-cli/internal/output"
 )
 
 var agentsCmd = &cobra.Command{
 	Use:   "agents",
 	Short: "Manage agents",
 	RunE: func(cmd *cobra.Command, args []string) error {
-		handled, err := commandfeatures.HandleSubcommandListing(cmd, clioutput.PrintSubcommands)
+		handled, err := commandfeatures.HandleSubcommandListing(cmd, tuioutput.PrintSubcommands)
 		if err != nil || handled {
 			return err
 		}

packages/cli/cmd/auth.go

@@ -3,20 +3,19 @@ package cmd
 import (
 	"fmt"
 
-	tuioutput "github.com/FTMahringer/go-tui-incubator/output"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
 	"github.com/synapse-dev/synapse-cli/internal/api"
 	"github.com/synapse-dev/synapse-cli/internal/commandfeatures"
 	"github.com/synapse-dev/synapse-cli/internal/config"
-	clioutput "github.com/synapse-dev/synapse-cli/internal/output"
+	tuioutput "github.com/synapse-dev/synapse-cli/internal/output"
 )
 
 var authCmd = &cobra.Command{
 	Use:   "auth",
 	Short: "Authentication commands",
 	RunE: func(cmd *cobra.Command, args []string) error {
-		handled, err := commandfeatures.HandleSubcommandListing(cmd, clioutput.PrintSubcommands)
+		handled, err := commandfeatures.HandleSubcommandListing(cmd, tuioutput.PrintSubcommands)
 		if err != nil || handled {
 			return err
 		}