bash devkit/setup/legacy/install-tools.sh
bash devkit/setup/legacy/setup.sh
bash devkit/setup/legacy/verify.sh

# Clone DevKit, then create symlinks
pwsh -File devkit/setup/sync.ps1 -Link


This backs up any existing files in `~/.claude/`, creates symlinks for all shared files, and generates a machine identity for multi-machine sync.

### Subcommands (`/devkit-sync`)
| `/devkit-sync push` | Commit changes and push to `sync/<machine-id>` branch |
| `/devkit-sync pull` | Fetch and pull latest from main |
| `/devkit-sync init` | First-time setup: create symlinks and machine identity |
| `/devkit-sync diff` | Show detailed diff of local changes vs main |
| `/devkit-sync unlink` | Replace symlinks with copies (portable snapshot) |
| `/devkit-sync resolve` | Resolve sync conflicts between machines |
| `/devkit-sync promote` | Graduate local patterns to universal rules |
| `/devkit-sync update` | Check version and upgrade to latest release |
| `/devkit-sync verify` | Check if DevKit updates reached all active projects |
| `/devkit-sync new-project` | Scaffold a new project with templates and profile |
| `/devkit-sync audit` | Check for redundant permissions in settings.json |

### Multi-machine workflow

1. Clone DevKit on each machine and run `sync.ps1 -Link`
2. The `SessionStart.sh` hook auto-pulls main at the start of every session
3. New patterns and gotchas accumulate via symlinks -- `/devkit-sync push` commits and pushes to a `sync/<machine-id>` branch
4. PRs merge each machine's changes into main, where other machines pick them up on next session start

Local-only files (`*.local.md`, `settings.local.json`, `.credentials*`) are never synced. See [ADR-0011](docs/ADR-0011-sync-architecture.md) for the full rationale and alternatives considered.

### Project registry

DevKit can track which projects on a machine consume its configuration via a project registry (`~/.devkit-registry.json`). This enables querying which projects have local rules to promote and which need updating after a DevKit change. The registry is machine-local and never committed to DevKit. See [docs/project-registry-schema.md](docs/project-registry-schema.md) for the schema and field descriptions.

### Forge support

DevKit supports GitHub natively via the `gh` CLI. Gitea repositories are supported through `tea` CLI behind a forge-detection wrapper that parses `git remote get-url origin` to choose the right tool automatically. Configure `forge.giteaUrl` in `~/.devkit-config.json` for self-hosted Gitea instances. See [docs/forge-abstraction.md](docs/forge-abstraction.md) for the full design and CLI mapping.

## Local Overrides

Rules files ending in `.local.md` provide machine-specific overrides that complement the universal rules. Claude Code loads all `*.md` files from `~/.claude/rules/` automatically, so a file like `~/.claude/rules/my-machine.local.md` is picked up alongside the synced rules -- no extra configuration needed.

**How it works:** Universal rules (`autolearn-patterns.md`, `known-gotchas.md`, etc.) are symlinked from DevKit and shared across machines. Local rules (`*.local.md`) are real files that live only on one machine. The sync system never touches them -- `.local.md` files are excluded via `.sync-manifest.json` `local_only_patterns` and `.gitignore`.

**When to use local overrides:**

- Machine-specific paths or tool locations (e.g., Python at a non-standard path)
- OS-specific gotchas that only apply to one workstation
- Patterns discovered during project work that aren't yet promoted to universal rules
- Temporary notes or reminders for the current machine

A starter template is available at [`project-templates/rules-local-template.md`](project-templates/rules-local-template.md). Copy it to `~/.claude/rules/` and rename with a `.local.md` suffix.

## Manual Setup

If you prefer to set things up yourself:

### Claude Code Configuration

```bash
# Copy global instructions
cp claude/CLAUDE.md ~/.claude/CLAUDE.md

# Copy rules (auto-loaded every session)
cp claude/rules/*.md ~/.claude/rules/

# Copy user-level skills (generic, available in all projects)
cp -r claude/skills/* ~/.claude/skills/
# Project-specific skills go in <project>/.claude/skills/ instead
# (e.g., dashboard, dev-mode, coordination-sync belong at project level)

# Copy agent templates
cp claude/agents/*.md ~/.claude/agents/

# Copy hooks
cp claude/hooks/* ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

# Create settings from template (only if none exists)
cp claude/settings.template.json ~/.claude/settings.json
# Then edit settings.json to adjust permissions and plugins

# Copy and customize the desktop config
cp mcp/claude-desktop.template.json "$HOME/.config/Claude/claude_desktop_config.json"
# Edit the file: replace <PATH> placeholders with machine-specific paths
# Secret tokens are read from environment variables (populated by HomeLabVault)
# See docs/credentials.md for the full credential workflow

# These go at your workspace root (parent of all projects)
WORKSPACE="$HOME/workspace"  # adjust to your path
cp devspace/.editorconfig "$WORKSPACE/.editorconfig"
cp devspace/.markdownlint.json "$WORKSPACE/.markdownlint.json"
cp -r devspace/templates "$WORKSPACE/.templates"
cp -r devspace/shared-vscode "$WORKSPACE/.shared-vscode"

# 1. Create the project directory
mkdir ~/workspace/my-project && cd ~/workspace/my-project
git init

# 2. Copy the CLAUDE.md template
cp ~/workspace/.templates/claude-md-template.md CLAUDE.md
# Edit CLAUDE.md with project-specific build commands and architecture

# 3. (Optional) Copy other templates as needed
cp ~/workspace/.templates/adr-template.md docs/decisions/ADR-001.md
cp ~/workspace/.templates/design-template.md docs/designs/DES-001.md

# 4. Follow the methodology (see METHODOLOGY.md)
# Phase 0: Write a concept brief
# Phase 1: Research the landscape
# Phase 2: Specification (requirements + decisions)
# ...