[docs] Update documentation for v1.8.0 (#85)

* [docs] Update documentation for v1.8.0

- Add rimba mcp and rimba completion to commands table in README
- Document rimba mcp with MCP tools reference and setup snippets
- Add --personal flag (init) and --no-push flag (sync) to command reference
- Update sync description to document auto-push after sync
- Update config examples to minimal form (worktree_dir/default_source auto-derived)
- Remove worktree_dir and default_source from field reference table
- Migrate .gitignore from .rimba.toml to .rimba/settings.local.toml
- Add .rimba/settings.toml (migrated from .rimba.toml)

* [docs] Update agent file templates and regenerate deployed files

- Add MCP server mention to all 4 agent templates (AGENTS.md, copilot, cursor, claude)
- Update copilot config shape to minimal (remove worktree_dir/default_source)
- Add rimba mcp to cursor top commands and claude decision logic
- Remove stale worktree_dir error from claude skill error table
- Fix missing space in error table formatting
- Regenerate all deployed agent files

Author: lugassawan

.claude/skills/rimba/SKILL.md

@@ -29,6 +29,7 @@ curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/insta
 | Run across worktrees | `rimba exec "<cmd>"` |
 | Check for conflicts | `rimba conflict-check` |
 | Check dependencies | `rimba deps status` |
+| Use MCP server | `rimba mcp` (stdio transport for AI agents) |
 
 ## JSON Output
 
@@ -50,14 +51,13 @@ Commands supporting `--json`: `list`, `status`, `exec`, `conflict-check`, `deps
 | Error | Cause | Fix |
 |-------|-------|-----|
 | "not a git repository" | Not inside a git repo | `cd` into a git repo |
-| ".rimba.toml not found" | rimba not initialized | Run `rimba init` |
-| "worktree_dir must not be empty" | Bad config | Check `.rimba.toml` |
+| "config not found" | rimba not initialized | Run `rimba init` |
 | "branch already exists" | Task name in use | Pick a different task name |
 | "worktree has uncommitted changes" | Dirty worktree | Commit or stash changes, or use `--force` |
 
 ## Best Practices
 
 - Prefer `rimba archive` over `rimba remove` to preserve branches
 - Use `--force` only when you understand the implications
-- Never modify `.rimba.toml` without asking the user
+- Never modify `.rimba/settings.toml` without asking the user
 - Always check `rimba status` before bulk operations

.cursor/rules/rimba.mdc

@@ -2,7 +2,7 @@
 description: rimba git worktree manager commands and workflows
 globs:
   - "*.go"
-  - ".rimba.toml"
+  - ".rimba/settings.toml"
 alwaysApply: false
 ---
 
@@ -22,6 +22,7 @@ See AGENTS.md at the repo root for full documentation.
 8. `rimba archive <task>` — remove worktree, keep branch
 9. `rimba exec <cmd>` — run across all worktrees
 10. `rimba clean --merged` — remove merged worktrees
+11. `rimba mcp` — start MCP server for AI tool integration
 
 ## Workflow Recipes
 
@@ -38,4 +39,4 @@ Envelope: `{"version", "command", "data"}` or `{"version", "command", "error", "
 
 - Prefer `archive` over `remove` to keep branches for reference.
 - Use `--force` only when you understand the implications.
-- Never modify `.rimba.toml` without asking the user.
+- Never modify `.rimba/settings.toml` without asking the user.

.github/copilot-instructions.md

@@ -12,12 +12,11 @@ See AGENTS.md at the repo root for full rimba documentation.
 - `rimba merge <task>` — merge back to source branch
 - `rimba clean --merged` — remove merged worktrees
 - `rimba exec <cmd>` — run command across all worktrees
+- `rimba mcp` — start MCP server for AI tool integration
 
-### Config Shape (`.rimba.toml`)
+### Config Shape (`.rimba/settings.toml`)
 
 ```toml
-worktree_dir = "../<repo>-worktrees"
-default_source = "main"
 copy_files = [".env", ".env.local", ".envrc", ".tool-versions"]
 post_create = []
 ```

.gitignore

@@ -33,7 +33,7 @@ custom-gcl
 .env
 
 # Rimba config (local to each repo)
-.rimba.toml
+.rimba/settings.local.toml
 
 # Editor/IDE
 # .idea/
@@ -47,4 +47,4 @@ local.properties
 *local.json
 
 # Worktrees
-.worktrees/
+.worktrees/

.rimba/settings.toml

@@ -0,0 +1,5 @@
+copy_files = ['.claude']
+
+[open]
+ide = 'code .'
+agent = 'claude'

AGENTS.md

@@ -4,7 +4,7 @@
 # rimba — Git Worktree Manager
 
 rimba manages parallel git worktrees so you can work on multiple tasks simultaneously.
-It is optional and detected via `.rimba.toml` in the repo root.
+It is optional and detected via `.rimba/settings.toml` in the repo root.
 
 ## Prerequisites
 
@@ -25,6 +25,7 @@ curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/insta
 | Sync & merge | `rimba sync [task]`, `rimba merge <task>` |
 | Clean up | `rimba clean --merged`, `rimba archive <task>`, `rimba remove <task>` |
 | Cross-cutting | `rimba exec <cmd>`, `rimba conflict-check`, `rimba deps status` |
+| AI integration | `rimba mcp` (MCP server for AI coding agents) |
 
 ## Workflow Recipes
 
@@ -57,6 +58,6 @@ Error: `{"version": "...", "command": "...", "error": "...", "code": "..."}`
 
 - Prefer `rimba archive` over `rimba remove` to preserve branches for later reference
 - Use `--force` only when you understand the implications (skips dirty checks)
-- Never modify `.rimba.toml` programmatically without asking the user
+- Never modify `.rimba/settings.toml` programmatically without asking the user
 
 <!-- END RIMBA -->

README.md

@@ -115,6 +115,8 @@ rimba remove my-feature
 | `rimba clean` | Prune stale references or remove merged/stale worktrees |
 | `rimba update` | Check for updates and replace the binary in place |
 | `rimba version` | Print version, commit, and build date |
+| `rimba mcp` | Start MCP server for AI tool integration |
+| `rimba completion` | Generate shell completion scripts (bash, zsh, fish, powershell) |
 
 > See [docs/commands.md](docs/commands.md) for the full reference with all flags, examples, and notes.
 
@@ -123,8 +125,6 @@ rimba remove my-feature
 `rimba init` creates a `.rimba/` directory with team-shared and personal config files:
 
 ```toml
-worktree_dir = '../myrepo-worktrees'
-default_source = 'main'
 copy_files = ['.env', '.env.local', '.envrc', '.tool-versions', '.vscode']
 post_create = ['./gradlew build']
 

docs/commands.md

@@ -31,6 +31,7 @@ rimba init --agent-files    # Also install AI agent instruction files
 | Flag | Description |
 |------|-------------|
 | `--agent-files` | Install AI agent instruction files (AGENTS.md, copilot, cursor, claude) |
+| `--personal` | Gitignore the entire `.rimba/` directory instead of just the local config file (for solo developers) |
 
 ---
 
@@ -263,11 +264,12 @@ rimba merge auth --no-ff                   # Force merge commit
 
 ### rimba sync
 
-Sync worktree(s) with the main branch by rebasing (default) or merging. Fetches the latest changes from origin first.
+Sync worktree(s) with the main branch by rebasing (default) or merging. Fetches the latest changes from origin first, then automatically pushes after a successful sync. Use `--no-push` to skip the push step.
 
 ```sh
-rimba sync my-feature                # Rebase a single worktree onto main
+rimba sync my-feature                # Rebase a single worktree onto main, then push
 rimba sync my-feature --merge        # Use merge instead of rebase
+rimba sync my-feature --no-push      # Sync without pushing
 rimba sync --all                     # Sync all eligible worktrees
 rimba sync --all --include-inherited # Include duplicate worktrees
 ```
@@ -277,8 +279,9 @@ rimba sync --all --include-inherited # Include duplicate worktrees
 | `--all` | Sync all eligible worktrees (skips dirty and inherited by default) |
 | `--merge` | Use merge instead of rebase |
 | `--include-inherited` | Include inherited/duplicate worktrees when using `--all` |
+| `--no-push` | Skip pushing after sync (useful for local-only rebase/merge) |
 
-> **Note:** Dirty worktrees are skipped with a warning. On conflict, the rebase is automatically aborted and a recovery hint is printed.
+> **Note:** Dirty worktrees are skipped with a warning. On conflict, the rebase is automatically aborted and a recovery hint is printed. After a successful sync, the branch is pushed to origin by default.
 
 ### rimba merge-plan
 
@@ -419,6 +422,55 @@ rimba deps install my-feature
 
 ---
 
+## AI Integration
+
+### rimba mcp
+
+Start a Model Context Protocol (MCP) server that exposes rimba's worktree management as tools for AI coding agents. The server runs over stdio and follows the MCP specification.
+
+```sh
+rimba mcp    # Start MCP server (stdio transport)
+```
+
+#### Setup
+
+**Claude Code** — add to `.mcp.json` or run:
+
+```sh
+claude mcp add rimba rimba mcp
+```
+
+**Cursor** — add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "rimba": {
+      "command": "rimba",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+#### MCP Tools
+
+| Tool | Description | Required Parameters |
+|------|-------------|---------------------|
+| `list` | List all worktrees with branch, path, and status | — |
+| `add` | Create a new worktree for a task | `task` |
+| `remove` | Remove a worktree and optionally delete its branch | `task` |
+| `status` | Show worktree dashboard with summary stats and age info | — |
+| `sync` | Sync worktree(s) with the main branch via rebase or merge, then push | `task` or `all` |
+| `merge` | Merge a worktree branch into main or another worktree | `source` |
+| `exec` | Run a shell command across matching worktrees in parallel | `command` |
+| `conflict-check` | Detect file overlaps between worktree branches | — |
+| `clean` | Clean up stale references, merged branches, or stale worktrees | `mode` (prune, merged, stale) |
+
+> **Note:** All tools return JSON responses. See `rimba mcp` help output for full parameter details.
+
+---
+
 ## Maintenance
 
 ### rimba clean
@@ -474,3 +526,18 @@ Print version, commit, and build date.
 rimba version
 # rimba v0.1.0 (commit: abc1234, built: 2026-01-01T00:00:00Z)
 ```
+
+---
+
+### rimba completion
+
+Generate shell completion scripts for bash, zsh, fish, or PowerShell.
+
+```sh
+rimba completion bash        # Generate bash completions
+rimba completion zsh         # Generate zsh completions
+rimba completion fish        # Generate fish completions
+rimba completion powershell  # Generate PowerShell completions
+```
+
+> **Note:** Follow the printed instructions after generating to install the completions for your shell.

docs/configuration.md

@@ -16,8 +16,6 @@ Local settings override team settings. Fields omitted from the local file inheri
 ### Team config (`.rimba/settings.toml`)
 
 ```toml
-worktree_dir = '../myrepo-worktrees'
-default_source = 'main'
 copy_files = ['.env', '.env.local', '.envrc', '.tool-versions', '.vscode']
 
 # Post-create hooks (run in new worktree directory)
@@ -74,8 +72,6 @@ rimba init
 
 | Field | Description | Default |
 |-------|-------------|---------|
-| `worktree_dir` | Directory for worktrees (relative to repo root) | `../<repo-name>-worktrees` |
-| `default_source` | Branch to create worktrees from | Default branch (e.g. `main`) |
 | `copy_files` | Files or directories to copy from repo root into new worktrees | `.env`, `.env.local`, `.envrc`, `.tool-versions` |
 | `post_create` | Shell commands to run in new worktrees after creation | (none) |
 | `open.<name>` | Named shortcut command for `rimba open --with <name>` | (none) |

internal/agentfile/content.go

@@ -32,6 +32,7 @@ curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/insta
 | Sync & merge | ` + "`" + `rimba sync [task]` + "`" + `, ` + "`" + `rimba merge <task>` + "`" + ` |
 | Clean up | ` + "`" + `rimba clean --merged` + "`" + `, ` + "`" + `rimba archive <task>` + "`" + `, ` + "`" + `rimba remove <task>` + "`" + ` |
 | Cross-cutting | ` + "`" + `rimba exec <cmd>` + "`" + `, ` + "`" + `rimba conflict-check` + "`" + `, ` + "`" + `rimba deps status` + "`" + ` |
+| AI integration | ` + "`" + `rimba mcp` + "`" + ` (MCP server for AI coding agents) |
 
 ## Workflow Recipes
 
@@ -85,12 +86,11 @@ See AGENTS.md at the repo root for full rimba documentation.
 - ` + "`" + `rimba merge <task>` + "`" + ` — merge back to source branch
 - ` + "`" + `rimba clean --merged` + "`" + ` — remove merged worktrees
 - ` + "`" + `rimba exec <cmd>` + "`" + ` — run command across all worktrees
+- ` + "`" + `rimba mcp` + "`" + ` — start MCP server for AI tool integration
 
 ### Config Shape (` + "`" + `.rimba/settings.toml` + "`" + `)
 
 ` + "```" + `toml
-worktree_dir = "../<repo>-worktrees"
-default_source = "main"
 copy_files = [".env", ".env.local", ".envrc", ".tool-versions"]
 post_create = []
 ` + "```" + `
@@ -130,6 +130,7 @@ See AGENTS.md at the repo root for full documentation.
 8. ` + "`" + `rimba archive <task>` + "`" + ` — remove worktree, keep branch
 9. ` + "`" + `rimba exec <cmd>` + "`" + ` — run across all worktrees
 10. ` + "`" + `rimba clean --merged` + "`" + ` — remove merged worktrees
+11. ` + "`" + `rimba mcp` + "`" + ` — start MCP server for AI tool integration
 
 ## Workflow Recipes
 
@@ -183,6 +184,7 @@ curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/insta
 | Run across worktrees | ` + "`" + `rimba exec "<cmd>"` + "`" + ` |
 | Check for conflicts | ` + "`" + `rimba conflict-check` + "`" + ` |
 | Check dependencies | ` + "`" + `rimba deps status` + "`" + ` |
+| Use MCP server | ` + "`" + `rimba mcp` + "`" + ` (stdio transport for AI agents) |
 
 ## JSON Output
 
@@ -204,8 +206,7 @@ Commands supporting ` + "`" + `--json` + "`" + `: ` + "`" + `list` + "`" + `, `
 | Error | Cause | Fix |
 |-------|-------|-----|
 | "not a git repository" | Not inside a git repo | ` + "`" + `cd` + "`" + ` into a git repo |
-| "config not found" | rimba not initialized | Run` + "`" + `rimba init` + "`" + ` |
-| "worktree_dir must not be empty" | Bad config | Check ` + "`" + `.rimba/settings.toml` + "`" + ` |
+| "config not found" | rimba not initialized | Run ` + "`" + `rimba init` + "`" + ` |
 | "branch already exists" | Task name in use | Pick a different task name |
 | "worktree has uncommitted changes" | Dirty worktree | Commit or stash changes, or use ` + "`" + `--force` + "`" + ` |