feat: add setup.sh and AGENTS.md

.claude/README.md

@@ -0,0 +1,68 @@
+# Claude Code Configuration
+
+This directory contains Claude Code configuration files for the Mix project.
+
+## Files
+
+### `settings.json` (Committed)
+Shared team settings that everyone uses. Contains:
+- **sessionStart hook**: Runs `scripts/setup.sh` automatically
+- **Default model**: Sonnet
+- **Default shell**: Bash
+
+### `settings.local.json` (Git-Ignored)
+**Create this file** for personal settings that override `settings.json`.
+
+Example:
+```json
+{
+  "model": {
+    "default": "opus"
+  },
+  "hooks": {
+    "preToolUse": "echo 'My custom hook'"
+  }
+}
+```
+
+## Settings Precedence
+
+Higher number = higher precedence (wins):
+
+1. User settings (`~/.claude/settings.json`)
+2. **Project settings** (`.claude/settings.json`) ← Committed
+3. **Project local settings** (`.claude/settings.local.json`) ← Git-ignored
+4. Command-line arguments
+5. Enterprise policies (cannot override)
+
+## Memory Files
+
+See the root directory for memory files:
+
+- **`AGENTS.md`** (Committed): Architecture and project context
+- **`CLAUDE.local.md`** (Symlink → AGENTS.md): Auto-created by setup.sh, git-ignored
+- **`CLAUDE.md`** (Git-Ignored): Optional personal instructions
+
+## Quick Start
+
+1. **For team setup**: Run `scripts/setup.sh` (auto-runs via sessionStart hook)
+   - Creates symlink: `CLAUDE.local.md` → `AGENTS.md`
+   - Claude Code reads `CLAUDE.local.md` which contains architecture context
+2. **For personal settings overrides**:
+   - Create `.claude/settings.local.json` if needed
+3. **Test setup**: Run `scripts/setup.sh` manually
+
+## How Memory Loading Works
+
+When Claude Code starts:
+1. Reads `CLAUDE.local.md` (which is a symlink to `AGENTS.md`)
+2. Gets full architecture context automatically
+3. No need for imports or manual configuration
+
+## Documentation
+
+- **Memory hierarchy (CLAUDE.local.md):** https://docs.claude.com/en/docs/claude-code/memory.md
+  - See "Project memory (local)" row in the table for `CLAUDE.local.md` reference
+- **Settings docs:** https://docs.claude.com/en/docs/claude-code/settings.md
+- **Hooks reference:** https://docs.claude.com/en/docs/claude-code/hooks-reference.md
+- **Setup guide (generic):** See `../CLAUDE_CODE_WEB_SETUP_GUIDE.md` in repo root

.claude/settings.json

@@ -0,0 +1,11 @@
+{
+  "hooks": {
+    "sessionStart": "scripts/setup.sh"
+  },
+  "model": {
+    "default": "sonnet"
+  },
+  "shell": {
+    "defaultShell": "/bin/bash"
+  }
+}

.gitignore

@@ -105,7 +105,8 @@ packages/mix/.cody/ignore
 
 .cursor
 .orbit
-CLAUDE.md
+CLAUDE.local.md
+.claude/settings.local.json
 .augment/env/setup.sh
 
 # API compatibility reports

AGENTS.md

@@ -0,0 +1,23 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Mix is a Melos-managed monorepo. Runtime code is in `packages/mix/lib/`, annotation APIs in `packages/mix_annotations/`, generators in `packages/mix_generator/`, and lint rules in `packages/mix_lint/`. Sample apps live under `examples/` and `packages/*/demo/`. Shared docs sit in `guides/`, marketing in `website/`, automation helpers in `scripts/`, and static art in `assets/`. Each package keeps unit tests in its `test/` folder.
+
+## Build, Test, and Development Commands
+- `melos bootstrap` — install dependencies and link local packages.
+- `melos run analyze` — run `dart analyze` plus Dart Code Metrics on every package.
+- `melos run gen:build` / `melos run gen:watch` — regenerate sources once or continuously via `build_runner`.
+- `melos run test:flutter`, `melos run test:dart`, `melos run test:coverage` — execute Flutter, pure Dart, or coverage suites.
+- `melos run ci` — shortcut that runs the primary Flutter and Dart test targets.
+
+## Coding Style & Naming Conventions
+Use standard Flutter formatting (two-space indent, trailing commas) and keep imports relative; both rules are enforced through `lints.yaml`. The workspace enables the `dot-shorthands` experiment, so remember to update `analysis_options.yaml` when creating new packages. `lints_with_dcm.yaml` layers Dart Code Metrics rules such as `member-ordering` and `arguments-ordering`; run `melos run lint:fix:all` before pushing to surface violations automatically. Name shared `Style` or `Variant` definitions descriptively (`const outlined = NamedVariant('outlined');`) and align file names with the primary class they export.
+
+## Testing Guidelines
+Author focused `*_test.dart` files grouped by widget, utility, or generator. Flutter-facing packages rely on `flutter_test`, while generators and lint packages use `dart test`. Always regenerate sources (`melos run gen:build`) before running tests that touch generated code. Use `melos run test:coverage` when altering rendering primitives, and include golden diffs or storybook screenshots in PRs whenever UI output changes.
+
+## Commit & Pull Request Guidelines
+Adopt Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`) as seen throughout history; keep the subject ≤72 characters and mention the impacted module (`feat: mix_generator adds StackBox hook`). PRs should explain intent, link issues (`Fixes #123`), highlight testing status, and attach screenshots for visual tweaks. Update changelogs when bumping versions, verify exports via `melos run exports`, and run `./scripts/verify_changelogs.sh packages` before release PRs.
+
+## Security & Automation Tips
+Pin tooling through `.fvm/flutter_sdk` to avoid SDK drift, and keep secrets out of version control (use ignored `.env` files inside `examples/` when necessary). Leverage `melos run api-check` or `dart scripts/api_check.dart` to compare public APIs before tagging a release.

CLAUDE.md

@@ -0,0 +1,5 @@
+# Mix Project - Claude Code Context
+
+> Project Context: @AGENTS.md
+
+This file imports AGENTS.md to provide full project context to Claude Code.

scripts/setup.sh

@@ -0,0 +1,224 @@
+#!/bin/bash
+# Setup script for Mix monorepo
+# Handles FVM, Melos, and workspace initialization
+# Compatible with both local and Claude Code remote environments
+
+set -e  # Exit immediately if a command exits with a non-zero status
+set -u  # Treat unset variables as an error
+
+# ANSI color codes for better output readability
+readonly GREEN='\033[0;32m'
+readonly BLUE='\033[0;34m'
+readonly YELLOW='\033[1;33m'
+readonly RED='\033[0;31m'
+readonly NC='\033[0m' # No Color
+
+# Logging functions
+log_info() {
+  echo -e "${BLUE}ℹ${NC} $1"
+}
+
+log_success() {
+  echo -e "${GREEN}✓${NC} $1"
+}
+
+log_warning() {
+  echo -e "${YELLOW}⚠${NC} $1"
+}
+
+log_error() {
+  echo -e "${RED}✗${NC} $1"
+  exit 1
+}
+
+log_step() {
+  echo ""
+  echo -e "${BLUE}▶${NC} ${GREEN}$1${NC}"
+  echo "─────────────────────────────────────────────────"
+}
+
+# Detect environment
+detect_environment() {
+  if [ "${CLAUDE_CODE_REMOTE:-false}" = "true" ]; then
+    log_info "Environment: Claude Code Remote"
+    export IS_REMOTE=true
+  else
+    log_info "Environment: Local"
+    export IS_REMOTE=false
+  fi
+}
+
+# Verify Claude Code memory setup
+verify_claude_memory() {
+  log_step "Verifying Claude Code memory"
+
+  if [ ! -f "AGENTS.md" ]; then
+    log_warning "AGENTS.md not found"
+    return 0
+  fi
+
+  if [ ! -f "CLAUDE.md" ]; then
+    log_warning "CLAUDE.md not found"
+    return 0
+  fi
+
+  log_success "AGENTS.md found"
+  log_success "CLAUDE.md found (imports AGENTS.md)"
+}
+
+# Ensure pub-cache bin is in PATH
+setup_path() {
+  log_step "Setting up environment PATH"
+
+  export PATH="$HOME/.pub-cache/bin:$PATH"
+
+  # For FVM, also ensure the default Flutter is accessible
+  if [ -d "$HOME/.fvm/default/bin" ]; then
+    export PATH="$HOME/.fvm/default/bin:$PATH"
+  fi
+
+  log_success "PATH configured"
+}
+
+# Check and install FVM
+setup_fvm() {
+  log_step "Setting up FVM (Flutter Version Management)"
+
+  if command -v fvm &> /dev/null; then
+    log_success "FVM already installed at $(which fvm)"
+    fvm --version
+  else
+    log_info "Installing FVM via dart pub global activate..."
+    dart pub global activate fvm
+    log_success "FVM installed"
+  fi
+}
+
+# Install Flutter using FVM based on .fvmrc configuration
+setup_flutter() {
+  log_step "Installing Flutter via FVM"
+
+  if [ ! -f ".fvmrc" ]; then
+    log_error "No .fvmrc file found. Cannot determine Flutter version."
+  fi
+
+  log_info "Reading FVM configuration from .fvmrc..."
+  cat .fvmrc
+
+  log_info "Installing Flutter version specified in .fvmrc..."
+  fvm install
+
+  log_info "Setting Flutter version for this project..."
+  fvm use --force
+
+  # Verify Flutter installation
+  log_info "Verifying Flutter installation..."
+  fvm flutter --version
+
+  log_success "Flutter ready via FVM"
+}
+
+# Install Melos
+setup_melos() {
+  log_step "Setting up Melos (Workspace Manager)"
+
+  if command -v melos &> /dev/null; then
+    log_success "Melos already installed at $(which melos)"
+    melos --version
+  else
+    log_info "Installing Melos via dart pub global activate..."
+    dart pub global activate melos
+    log_success "Melos installed"
+  fi
+}
+
+# Install DCM (Dart Code Metrics)
+setup_dcm() {
+  log_step "Setting up DCM (Dart Code Metrics)"
+
+  if command -v dcm &> /dev/null; then
+    log_success "DCM already installed at $(which dcm)"
+    dcm --version
+  else
+    log_info "Installing DCM via dart pub global activate..."
+    dart pub global activate dart_code_metrics
+    log_success "DCM installed"
+  fi
+}
+
+# Bootstrap all packages in the workspace
+bootstrap_workspace() {
+  log_step "Bootstrapping Mix workspace with Melos"
+
+  log_info "Running melos bootstrap..."
+  log_info "This will fetch dependencies for all packages in the monorepo"
+
+  melos bootstrap --verbose
+
+  log_success "Workspace bootstrapped successfully"
+}
+
+# Generate code for all packages
+generate_code() {
+  log_step "Generating code with build_runner"
+
+  log_info "Running melos run gen:build..."
+  log_info "This will generate code for all packages that depend on build_runner"
+
+  melos run gen:build
+
+  log_success "Code generation complete"
+}
+
+# Verify the setup
+verify_setup() {
+  log_step "Verifying setup"
+
+  log_info "Checking workspace packages..."
+  melos list
+
+  log_info "Checking Flutter doctor..."
+  fvm flutter doctor -v
+
+  log_success "Setup verified successfully"
+}
+
+# Main setup flow
+main() {
+  echo ""
+  echo "════════════════════════════════════════════════"
+  echo "  Mix Monorepo Setup"
+  echo "════════════════════════════════════════════════"
+  echo ""
+
+  detect_environment
+  verify_claude_memory
+  setup_path
+  setup_fvm
+  setup_flutter
+  setup_melos
+  setup_dcm
+  bootstrap_workspace
+  generate_code
+  verify_setup
+
+  echo ""
+  echo "════════════════════════════════════════════════"
+  echo -e "  ${GREEN}✓ Setup Complete!${NC}"
+  echo "════════════════════════════════════════════════"
+  echo ""
+  echo "Available Melos commands:"
+  echo "  • melos run analyze      - Run static analysis"
+  echo "  • melos run test:flutter - Run Flutter tests"
+  echo "  • melos run test:dart    - Run Dart tests"
+  echo "  • melos run gen:build    - Regenerate code"
+  echo "  • melos run fix          - Apply lint fixes"
+  echo ""
+  echo "Ready to build with Mix! 🎨"
+  echo ""
+}
+
+# Run main function
+main
+
+exit 0