feat: separate local state from team config

Implement three-tier configuration architecture:
- Project config (project-root/arbor.yaml) - scaffold steps, not versioned
- Repository config (worktree/arbor.yaml) - team defaults, versioned
- Local state (worktree/.arbor.local) - runtime state, gitignored

Changes:
- Add LocalState type with ReadLocalState/WriteLocalState functions
- Migrate db_suffix from arbor.yaml to .arbor.local automatically
- Update ScaffoldManager to use local state for db_suffix
- Add repo config auto-detection in init command
- Add --use-repo-config flag (defaults to true)
- Add gitignore warning for .arbor.local
- Update all tests to use .arbor.local
- Update documentation with configuration hierarchy

Benefits:
- Clear separation of team config vs local state
- No conflicts from db_suffix in version control
- Easy team onboarding with shared scaffold config
- Automatic migration for existing projects

Author: michaeldyrynda

AGENTS.md

@@ -46,10 +46,12 @@ arbor remove feature-my-feature  # When done
 
 ### Config Files
 
-| Config | Location | Purpose |
-|--------|----------|---------|
-| Project | `arbor.yaml` in worktree root | Project-specific settings |
-| Global | `~/.config/arbor/arbor.yaml` | User defaults |
+| Config | Location | Purpose | Versioned? |
+|--------|----------|---------|------------|
+| Project | `<project-root>/arbor.yaml` | Project-specific settings, scaffold config | No (not in a repo) |
+| Repository | `<worktree>/arbor.yaml` | Team defaults (copied during init) | Yes (committed to git) |
+| Local State | `<worktree>/.arbor.local` | Runtime state (db_suffix) | No (gitignored) |
+| Global | `~/.config/arbor/arbor.yaml` | User defaults | No (local machine) |
 
 ### Step Naming
 

README.md

@@ -184,7 +184,81 @@ arbor scaffold main
 
 ## Configuration
 
-Arbor uses a configuration file to define scaffold steps for `init` and `work` commands. Configuration is read from `arbor.yaml` in your project root.
+Arbor uses a three-tier configuration system to separate team configuration from local state.
+
+### Configuration Hierarchy
+
+#### 1. Project Config (`<project-root>/arbor.yaml`)
+
+Located at the project root (alongside `.bare/`), this file contains:
+- Scaffold steps and cleanup steps
+- Preset selection
+- Tool configurations
+- Project-wide settings
+
+This file is **not versioned** (the project root is not a git repository).
+
+During `arbor init`, if an `arbor.yaml` file is found in the repository, you'll be prompted to copy it to the project root.
+
+#### 2. Repository Config (`<worktree>/arbor.yaml`)
+
+Located inside each worktree and **committed to git**, this file contains:
+- Team default scaffold steps
+- Shared cleanup steps
+- Tool configurations
+
+This file serves as the source of truth for team configuration and is copied to the project root during `arbor init`.
+
+#### 3. Local State (`<worktree>/.arbor.local`)
+
+Located inside each worktree and **NOT versioned** (should be in `.gitignore`), this file contains:
+- `db_suffix` - unique database suffix for the worktree
+- Other worktree-specific runtime state
+
+This file is automatically created by Arbor and should never be committed.
+
+**Example `.gitignore` entry:**
+```
+.arbor.local
+```
+
+**Example `.arbor.local` file:**
+```yaml
+db_suffix: "sunset"
+```
+
+### Sharing Team Configuration
+
+To share scaffold configuration with your team:
+
+1. Create `arbor.yaml` in your repository with scaffold steps:
+```yaml
+preset: laravel
+scaffold:
+  steps:
+    - name: file.copy
+      from: .env.example
+      to: .env
+    - name: db.create
+    - name: php.composer
+      args: ["install"]
+```
+
+2. Commit and push to git:
+```bash
+git add arbor.yaml
+git commit -m "Add Arbor scaffold configuration"
+git push
+```
+
+3. Team members run `arbor init`:
+```bash
+arbor init user/repo
+# → Found arbor.yaml in repository. Copy to project root for team config? [Y/n]
+# → Press Enter to use team config
+```
+
+The config will be automatically copied to their project root and used for all worktrees.
 
 ### Scaffold Steps
 
@@ -244,7 +318,7 @@ All steps support template variables that are replaced at runtime:
 - Suffix is generated once per `init` or `work` invocation and shared across all `db.create` steps
 - Auto-detects engine from `DB_CONNECTION` in `.env`
 - Retries up to 5 times on collision
-- Persists suffix to worktree-local `arbor.yaml` for cleanup
+- Persists suffix to `.arbor.local` for cleanup
 
 **Multiple databases with shared suffix:**
 

internal/cli/gitignore.go

@@ -0,0 +1,25 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+
+	"github.com/michaeldyrynda/arbor/internal/git"
+	"github.com/michaeldyrynda/arbor/internal/ui"
+)
+
+// checkArborLocalGitignore checks if .arbor.local is gitignored and warns if not
+func checkArborLocalGitignore(worktreePath string) {
+	// Check if .arbor.local exists
+	localStatePath := filepath.Join(worktreePath, ".arbor.local")
+	if _, err := os.Stat(localStatePath); os.IsNotExist(err) {
+		return
+	}
+
+	ignored, err := git.IsIgnored(worktreePath, ".arbor.local")
+	if err == nil && ignored {
+		return
+	}
+
+	ui.PrintWarning("Add .arbor.local to .gitignore to prevent committing local state")
+}

internal/cli/init.go

@@ -2,9 +2,11 @@ package cli
 
 import (
 	"fmt"
+	"os"
 	"path/filepath"
 
 	"github.com/spf13/cobra"
+	"gopkg.in/yaml.v3"
 
 	"github.com/michaeldyrynda/arbor/internal/config"
 	"github.com/michaeldyrynda/arbor/internal/git"
@@ -98,6 +100,11 @@ Arguments:
 			SiteName:      siteName,
 		}
 
+		// Check for arbor.yaml in the cloned repository
+		if err := checkAndCopyRepoConfig(cmd, mainPath, absPath, cfg); err != nil {
+			return err
+		}
+
 		preset := mustGetString(cmd, "preset")
 
 		presetManager := presets.NewManager()
@@ -141,6 +148,11 @@ Arguments:
 			ui.PrintInfo("Skipped scaffold (use 'arbor scaffold main' to scaffold manually)")
 		}
 
+		// Check if .arbor.local should be gitignored
+		if !quiet {
+			checkArborLocalGitignore(mainPath)
+		}
+
 		ui.PrintDone("Repository ready!")
 		ui.PrintInfo(fmt.Sprintf("cd %s", absPath))
 		ui.PrintInfo("arbor work feature/my-feature")
@@ -154,4 +166,76 @@ func init() {
 
 	initCmd.Flags().String("preset", "", "Project preset (laravel, php)")
 	initCmd.Flags().Bool("skip-scaffold", false, "Skip scaffold steps during init")
+	initCmd.Flags().Bool("use-repo-config", true, "Automatically use repository config (non-interactive)")
+}
+
+// checkAndCopyRepoConfig checks for arbor.yaml in the repository and prompts to copy it
+func checkAndCopyRepoConfig(cmd *cobra.Command, mainPath, projectPath string, cfg *config.Config) error {
+	repoConfigPath := filepath.Join(mainPath, "arbor.yaml")
+	if _, err := os.Stat(repoConfigPath); os.IsNotExist(err) {
+		return nil
+	}
+
+	shouldCopy := false
+
+	if ui.IsInteractive() {
+		confirmed, err := ui.Confirm("Found arbor.yaml in repository. Copy to project root for team config?")
+		if err != nil {
+			return fmt.Errorf("prompting for config copy: %w", err)
+		}
+		shouldCopy = confirmed
+	} else {
+		// Non-interactive: use --use-repo-config flag (default true)
+		shouldCopy = mustGetBool(cmd, "use-repo-config")
+	}
+
+	if !shouldCopy {
+		return nil
+	}
+
+	projectConfigPath := filepath.Join(projectPath, "arbor.yaml")
+
+	// Read repo config
+	repoConfigData, err := os.ReadFile(repoConfigPath)
+	if err != nil {
+		return fmt.Errorf("reading repository config: %w", err)
+	}
+
+	// Parse and clean it (remove db_suffix if present)
+	var configData map[string]interface{}
+	if err := yaml.Unmarshal(repoConfigData, &configData); err != nil {
+		return fmt.Errorf("parsing repository config: %w", err)
+	}
+
+	// Remove local-only fields
+	delete(configData, "db_suffix")
+
+	// Always override site_name based on local path after copying team config
+	configData["site_name"] = cfg.SiteName
+
+	// Write to project root
+	cleanedData, err := yaml.Marshal(configData)
+	if err != nil {
+		return fmt.Errorf("marshaling cleaned config: %w", err)
+	}
+
+	if err := os.WriteFile(projectConfigPath, cleanedData, 0644); err != nil {
+		return fmt.Errorf("writing project config: %w", err)
+	}
+
+	ui.PrintSuccess("Copied arbor.yaml to project root")
+
+	// Reload config to get scaffold steps
+	reloadedCfg, err := config.LoadProject(projectPath)
+	if err != nil {
+		return fmt.Errorf("reloading config: %w", err)
+	}
+
+	// Update cfg with reloaded scaffold/cleanup steps
+	cfg.Scaffold = reloadedCfg.Scaffold
+	cfg.Cleanup = reloadedCfg.Cleanup
+	cfg.Preset = reloadedCfg.Preset
+	cfg.Tools = reloadedCfg.Tools
+
+	return nil
 }

internal/cli/work.go

@@ -134,6 +134,11 @@ available branches or entering a new branch name.`,
 			if err := pc.ScaffoldManager().RunScaffold(absWorktreePath, branch, repoName, siteName, preset, pc.Config, false, verbose, quiet); err != nil {
 				ui.PrintErrorWithHint("Scaffold steps failed", err.Error())
 			}
+
+			// Check if .arbor.local should be gitignored
+			if !quiet {
+				checkArborLocalGitignore(absWorktreePath)
+			}
 		} else {
 			ui.PrintInfo("[DRY RUN] Would run scaffold steps")
 		}

internal/config/local_state.go

@@ -0,0 +1,69 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"gopkg.in/yaml.v3"
+)
+
+// LocalState represents worktree-local state that should never be committed
+type LocalState struct {
+	DbSuffix string `yaml:"db_suffix"`
+}
+
+// ReadLocalState reads worktree-local state from .arbor.local
+func ReadLocalState(worktreePath string) (*LocalState, error) {
+	configPath := filepath.Join(worktreePath, ".arbor.local")
+
+	if _, err := os.Stat(configPath); os.IsNotExist(err) {
+		return &LocalState{}, nil
+	}
+
+	content, err := os.ReadFile(configPath)
+	if err != nil {
+		return nil, fmt.Errorf("reading local state: %w", err)
+	}
+
+	var state LocalState
+	if err := yaml.Unmarshal(content, &state); err != nil {
+		return nil, fmt.Errorf("parsing local state: %w", err)
+	}
+
+	return &state, nil
+}
+
+// WriteLocalState writes worktree-local state to .arbor.local
+func WriteLocalState(worktreePath string, data LocalState) error {
+	configPath := filepath.Join(worktreePath, ".arbor.local")
+
+	// Read existing state if it exists
+	var existing map[string]interface{}
+	if content, err := os.ReadFile(configPath); err == nil {
+		if err := yaml.Unmarshal(content, &existing); err != nil {
+			return fmt.Errorf("parsing existing local state: %w", err)
+		}
+	}
+
+	if existing == nil {
+		existing = make(map[string]interface{})
+	}
+
+	// Merge new data into existing state
+	if data.DbSuffix != "" {
+		existing["db_suffix"] = data.DbSuffix
+	}
+
+	// Marshal and write
+	content, err := yaml.Marshal(existing)
+	if err != nil {
+		return fmt.Errorf("marshaling local state: %w", err)
+	}
+
+	if err := os.WriteFile(configPath, content, 0644); err != nil {
+		return fmt.Errorf("writing local state: %w", err)
+	}
+
+	return nil
+}