diff --git a/.core/docs/core-folder-spec.md b/.core/docs/core-folder-spec.md
new file mode 100644
index 0000000..a185db1
--- /dev/null
+++ b/.core/docs/core-folder-spec.md
@@ -0,0 +1,319 @@
+# .core/ Folder Specification
+
+This document defines the `.core/` folder structure used across Host UK packages for configuration, tooling integration, and development environment setup.
+
+## Overview
+
+The `.core/` folder provides a standardised location for:
+- Build and development configuration
+- Claude Code plugin integration
+- VM/container definitions
+- Development environment settings
+
+## Directory Structure
+
+```
+package/.core/
+├── config.yaml           # Build targets, test commands, deploy config
+├── workspace.yaml        # Workspace-level config (devops repo only)
+├── plugin/               # Claude Code integration
+│   ├── plugin.json       # Plugin manifest
+│   ├── skills/           # Context-aware skills
+│   └── hooks/            # Pre/post command hooks
+├── linuxkit/             # VM/container definitions (if applicable)
+│   ├── kernel.yaml
+│   └── image.yaml
+└── run.yaml              # Development environment config
+```
+
+## Configuration Files
+
+### config.yaml
+
+Package-level build and runtime configuration.
+
+```yaml
+version: 1
+
+# Build configuration
+build:
+  targets:
+    - name: default
+      command: composer build
+    - name: production
+      command: composer build:prod
+      env:
+        APP_ENV: production
+
+# Test configuration
+test:
+  command: composer test
+  coverage: true
+  parallel: true
+
+# Lint configuration
+lint:
+  command: ./vendor/bin/pint
+  fix_command: ./vendor/bin/pint --dirty
+
+# Deploy configuration (if applicable)
+deploy:
+  staging:
+    command: ./deploy.sh staging
+  production:
+    command: ./deploy.sh production
+    requires_approval: true
+```
+
+### workspace.yaml
+
+Workspace-level configuration (only in `core-devops`).
+
+```yaml
+version: 1
+
+# Active package for unified commands
+active: core-php
+
+# Default package types for setup
+default_only:
+  - foundation
+  - module
+
+# Paths
+packages_dir: ./packages
+
+# Workspace settings
+settings:
+  suggest_core_commands: true
+  show_active_in_prompt: true
+```
+
+### run.yaml
+
+Development environment configuration.
+
+```yaml
+version: 1
+
+# Services required for development
+services:
+  - name: database
+    image: postgres:16
+    port: 5432
+    env:
+      POSTGRES_DB: core_dev
+      POSTGRES_USER: core
+      POSTGRES_PASSWORD: secret
+
+  - name: redis
+    image: redis:7
+    port: 6379
+
+  - name: mailpit
+    image: axllent/mailpit
+    port: 8025
+
+# Development server
+dev:
+  command: php artisan serve
+  port: 8000
+  watch:
+    - app/
+    - resources/
+
+# Environment variables
+env:
+  APP_ENV: local
+  APP_DEBUG: true
+  DB_CONNECTION: pgsql
+```
+
+## Claude Code Plugin
+
+### plugin.json
+
+The plugin manifest defines skills, hooks, and commands for Claude Code integration.
+
+```json
+{
+  "$schema": "https://claude.ai/code/plugin-schema.json",
+  "name": "package-name",
+  "version": "1.0.0",
+  "description": "Claude Code integration for this package",
+
+  "skills": [
+    {
+      "name": "skill-name",
+      "file": "skills/skill-name.md",
+      "description": "What this skill provides"
+    }
+  ],
+
+  "hooks": {
+    "pre_command": [
+      {
+        "pattern": "^command-pattern$",
+        "script": "hooks/script.sh",
+        "description": "What this hook does"
+      }
+    ]
+  },
+
+  "commands": {
+    "command-name": {
+      "description": "What this command does",
+      "run": "actual-command"
+    }
+  }
+}
+```
+
+### Skills (skills/*.md)
+
+Markdown files providing context-aware guidance for Claude Code. Skills are loaded when relevant to the user's query.
+
+```markdown
+# Skill Name
+
+Describe what this skill provides.
+
+## Context
+
+When to use this skill.
+
+## Commands
+
+Relevant commands and examples.
+
+## Tips
+
+Best practices and gotchas.
+```
+
+### Hooks (hooks/*.sh)
+
+Shell scripts executed before or after commands. Hooks should:
+- Be executable (`chmod +x`)
+- Exit 0 for informational hooks (don't block)
+- Exit non-zero to block the command (with reason)
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# Hook logic here
+
+exit 0  # Don't block
+```
+
+## LinuxKit (linuxkit/)
+
+For packages that deploy as VMs or containers.
+
+### kernel.yaml
+
+```yaml
+kernel:
+  image: linuxkit/kernel:6.6
+  cmdline: "console=tty0"
+```
+
+### image.yaml
+
+```yaml
+image:
+  - linuxkit/init:v1.0.1
+  - linuxkit/runc:v1.0.0
+  - linuxkit/containerd:v1.0.0
+```
+
+## Package-Type Specific Patterns
+
+### Foundation (core-php)
+
+```
+core-php/.core/
+├── config.yaml           # Build targets for framework
+├── plugin/
+│   └── skills/
+│       ├── events.md     # Event system guidance
+│       ├── modules.md    # Module loading patterns
+│       └── lifecycle.md  # Lifecycle events
+└── run.yaml              # Test environment setup
+```
+
+### Module (core-tenant, core-admin, etc.)
+
+```
+core-tenant/.core/
+├── config.yaml           # Module-specific build
+├── plugin/
+│   └── skills/
+│       └── tenancy.md    # Multi-tenancy patterns
+└── run.yaml              # Required services (database)
+```
+
+### Product (core-bio, core-social, etc.)
+
+```
+core-bio/.core/
+├── config.yaml           # Build and deploy targets
+├── plugin/
+│   └── skills/
+│       └── bio.md        # Product-specific guidance
+├── linuxkit/             # VM definitions for deployment
+│   ├── kernel.yaml
+│   └── image.yaml
+└── run.yaml              # Full dev environment
+```
+
+### Workspace (core-devops)
+
+```
+core-devops/.core/
+├── workspace.yaml        # Active package, paths
+├── plugin/
+│   ├── plugin.json
+│   └── skills/
+│       ├── workspace.md      # Multi-repo navigation
+│       ├── switch-package.md # Package switching
+│       └── package-status.md # Status checking
+└── docs/
+    └── core-folder-spec.md   # This file
+```
+
+## Core CLI Integration
+
+The `core` CLI reads configuration from `.core/`:
+
+| File | CLI Command | Purpose |
+|------|-------------|---------|
+| `workspace.yaml` | `core workspace` | Active package, paths |
+| `config.yaml` | `core build`, `core test` | Build/test commands |
+| `run.yaml` | `core run` | Dev environment |
+
+## Best Practices
+
+1. **Always include `version: 1`** in YAML files for future compatibility
+2. **Keep skills focused** - one concept per skill file
+3. **Hooks should be fast** - don't slow down commands
+4. **Use relative paths** - avoid hardcoded absolute paths
+5. **Document non-obvious settings** with inline comments
+
+## Migration Guide
+
+To add `.core/` to an existing package:
+
+1. Create the directory structure:
+   ```bash
+   mkdir -p .core/plugin/skills .core/plugin/hooks
+   ```
+
+2. Add `config.yaml` with build/test commands
+
+3. Add `plugin.json` with package-specific skills
+
+4. Add relevant skills in `skills/`
+
+5. Update `.gitignore` if needed (don't ignore `.core/`)
diff --git a/.core/plugin/hooks/prefer-core.sh b/.core/plugin/hooks/prefer-core.sh
new file mode 100755
index 0000000..dba1ecd
--- /dev/null
+++ b/.core/plugin/hooks/prefer-core.sh
@@ -0,0 +1,43 @@
+#!/bin/bash
+# prefer-core.sh - Suggest core CLI commands over raw commands
+#
+# This hook is called before certain commands to suggest core CLI equivalents.
+# It's informational only and doesn't block the original command.
+
+set -euo pipefail
+
+COMMAND="${1:-}"
+
+suggest() {
+    echo ""
+    echo "💡 Tip: Consider using the core CLI instead:"
+    echo "   $1"
+    echo ""
+}
+
+case "$COMMAND" in
+    "git add"*)
+        suggest "core commit (stages and commits with Claude-assisted messages)"
+        ;;
+    "git commit"*)
+        suggest "core commit (Claude-assisted commit messages)"
+        ;;
+    "git push"*)
+        suggest "core push (pushes all repos with unpushed commits)"
+        ;;
+    "git pull"*)
+        suggest "core pull (pulls all repos that are behind)"
+        ;;
+    "composer test"*)
+        suggest "core php test (runs from workspace root, targets active package)"
+        ;;
+    "composer lint"*)
+        suggest "core php lint (runs from workspace root, targets active package)"
+        ;;
+    *)
+        # No suggestion for this command
+        ;;
+esac
+
+# Always exit 0 - this is informational, not blocking
+exit 0
diff --git a/.core/plugin/plugin.json b/.core/plugin/plugin.json
new file mode 100644
index 0000000..509e23e
--- /dev/null
+++ b/.core/plugin/plugin.json
@@ -0,0 +1,55 @@
+{
+  "$schema": "https://claude.ai/code/plugin-schema.json",
+  "name": "host-uk-workspace",
+  "version": "1.0.0",
+  "description": "Claude Code integration for Host UK developer workspace",
+
+  "skills": [
+    {
+      "name": "workspace",
+      "file": "skills/workspace.md",
+      "description": "Navigate and manage the Host UK multi-repo workspace"
+    },
+    {
+      "name": "switch-package",
+      "file": "skills/switch-package.md",
+      "description": "Switch the active package for core CLI commands"
+    },
+    {
+      "name": "package-status",
+      "file": "skills/package-status.md",
+      "description": "Show status of all packages in the workspace"
+    }
+  ],
+
+  "hooks": {
+    "pre_command": [
+      {
+        "pattern": "^(git (add|commit|push|pull)|composer (test|lint))$",
+        "script": "hooks/prefer-core.sh",
+        "description": "Suggest core CLI equivalents for common commands"
+      }
+    ]
+  },
+
+  "commands": {
+    "status": {
+      "description": "Show workspace and package status",
+      "run": "core health"
+    },
+    "test": {
+      "description": "Run tests in active package",
+      "run": "core php test"
+    },
+    "lint": {
+      "description": "Run linter in active package",
+      "run": "core php lint"
+    }
+  },
+
+  "context": {
+    "workspace_root": true,
+    "registry_file": "repos.yaml",
+    "packages_dir": "packages"
+  }
+}
diff --git a/.core/plugin/skills/package-status.md b/.core/plugin/skills/package-status.md
new file mode 100644
index 0000000..9b5e6cb
--- /dev/null
+++ b/.core/plugin/skills/package-status.md
@@ -0,0 +1,70 @@
+# Package Status Skill
+
+Show the status of all packages in the Host UK workspace.
+
+## Quick Status
+
+Run from workspace root:
+
+```bash
+core health
+```
+
+Output example:
+```
+18 repos │ 2 dirty │ 1 behind │ synced
+```
+
+## Detailed Status
+
+For a full status table:
+
+```bash
+core work --status
+```
+
+Output shows:
+- Package name
+- Git status (clean/dirty/staged)
+- Branch and tracking
+- Ahead/behind remote
+
+## Check Specific Package
+
+```bash
+cd packages/core-php
+git status
+```
+
+Or check all dirty repos:
+
+```bash
+core work --status | grep -v "clean"
+```
+
+## Common Statuses
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| `clean` | No changes | Ready to work |
+| `dirty` | Uncommitted changes | Commit with `core commit` |
+| `ahead` | Local commits to push | Push with `core push` |
+| `behind` | Remote has new commits | Pull with `core pull` |
+| `diverged` | Both ahead and behind | Manual merge needed |
+
+## Workflow Commands
+
+```bash
+core work                   # Full workflow: status → commit → push
+core commit                 # Commit dirty repos (Claude-assisted)
+core push                   # Push repos with unpushed commits
+core pull                   # Pull repos that are behind
+```
+
+## GitHub Status
+
+```bash
+core ci                     # GitHub Actions status
+core issues                 # Open issues across repos
+core reviews                # PRs needing review
+```
diff --git a/.core/plugin/skills/switch-package.md b/.core/plugin/skills/switch-package.md
new file mode 100644
index 0000000..5837961
--- /dev/null
+++ b/.core/plugin/skills/switch-package.md
@@ -0,0 +1,52 @@
+# Switch Package Skill
+
+Switch the active package for the Host UK workspace.
+
+## Usage
+
+To switch the active package, edit `.core/workspace.yaml` and change the `active` field:
+
+```yaml
+# .core/workspace.yaml
+active: core-tenant  # Change this to the desired package
+```
+
+## Available Packages
+
+| Package | Type | Description |
+|---------|------|-------------|
+| `core-php` | foundation | Core PHP framework |
+| `core-tenant` | module | Multi-tenancy, workspaces |
+| `core-admin` | module | Admin panel, Livewire |
+| `core-api` | module | REST API, rate limiting |
+| `core-mcp` | module | MCP server framework |
+| `core-agentic` | module | AI agent orchestration |
+| `core-bio` | product | Link-in-bio pages |
+| `core-social` | product | Social media scheduling |
+| `core-analytics` | product | Privacy-first analytics |
+| `core-notify` | product | Push notifications |
+| `core-trust` | product | Social proof widgets |
+| `core-support` | product | Helpdesk, tickets |
+| `core-commerce` | module | Billing, Stripe |
+| `core-content` | module | CMS, pages, blog |
+| `core-tools` | module | Developer utilities |
+| `core-uptelligence` | module | Server monitoring |
+| `core-developer` | module | Developer portal |
+| `core-template` | template | Starter template |
+
+## After Switching
+
+After changing the active package:
+
+1. Commands like `core php test` will target the new package
+2. Read the package's CLAUDE.md for specific guidance: `packages/{package}/CLAUDE.md`
+3. Install dependencies if needed: `cd packages/{package} && composer install`
+
+## Quick Switch (CLI - Future)
+
+Once `core workspace` commands are implemented:
+
+```bash
+core workspace active core-tenant    # Switch to core-tenant
+core workspace active               # Show current active package
+```
diff --git a/.core/plugin/skills/workspace.md b/.core/plugin/skills/workspace.md
new file mode 100644
index 0000000..be4718e
--- /dev/null
+++ b/.core/plugin/skills/workspace.md
@@ -0,0 +1,111 @@
+# Workspace Navigation Skill
+
+You are working in the **Host UK developer workspace** - a federated monorepo containing 18 Laravel packages.
+
+## Workspace Structure
+
+```
+core-devops/                    # You are here (workspace root)
+├── .core/
+│   ├── workspace.yaml          # Active package config
+│   └── plugin/                 # Claude Code integration
+├── packages/                   # All packages cloned here
+│   ├── core-php/               # Foundation (no deps)
+│   ├── core-tenant/            # Multi-tenancy
+│   ├── core-admin/             # Admin panel
+│   ├── core-api/               # REST API
+│   ├── core-mcp/               # MCP server
+│   ├── core-agentic/           # AI agents
+│   ├── core-bio/               # Product: link-in-bio
+│   ├── core-social/            # Product: social scheduling
+│   ├── core-analytics/         # Product: analytics
+│   ├── core-notify/            # Product: push notifications
+│   ├── core-trust/             # Product: social proof
+│   ├── core-support/           # Product: helpdesk
+│   ├── core-commerce/          # Billing, Stripe
+│   ├── core-content/           # CMS
+│   ├── core-tools/             # Developer utilities
+│   ├── core-uptelligence/      # Server monitoring
+│   ├── core-developer/         # Developer portal
+│   └── core-template/          # Starter template
+└── repos.yaml                  # Package registry
+```
+
+## Key Commands
+
+### Workspace-level (run from root)
+```bash
+core health                     # Quick status: "18 repos │ clean │ synced"
+core work                       # Full workflow: status → commit → push
+core work --status              # Status table only
+core commit                     # Claude-assisted commits for dirty repos
+core push                       # Push repos with unpushed commits
+core pull                       # Pull repos that are behind
+```
+
+### Package-level (run from root, targets active package)
+```bash
+core php test                   # Run Pest tests in active package
+core php lint                   # Run Pint linter in active package
+core php dev                    # Start Vite dev server
+```
+
+### GitHub integration
+```bash
+core issues                     # Open issues across repos
+core issues --assignee @me      # Issues assigned to you
+core reviews                    # PRs needing review
+core ci                         # GitHub Actions status
+```
+
+### Analysis
+```bash
+core impact core-php            # Show what depends on core-php
+```
+
+## Active Package
+
+The **active package** is configured in `.core/workspace.yaml`. Commands like `core php test` run in the active package when executed from the workspace root.
+
+To check or change the active package:
+```bash
+# Check current active package
+cat .core/workspace.yaml | grep "active:"
+
+# Change active package (edit the file)
+# active: core-tenant
+```
+
+## Package Types
+
+Defined in `repos.yaml`:
+- **foundation**: `core-php` - base framework, zero dependencies
+- **module**: Infrastructure packages (tenant, admin, api, mcp, etc.)
+- **product**: User-facing apps (bio, social, analytics, etc.)
+- **template**: Starter for new projects
+- **meta**: This workspace repo (core-devops)
+
+## Working in a Specific Package
+
+When you need to work in a specific package:
+
+1. **Navigate to it**: `cd packages/core-tenant`
+2. **Read its CLAUDE.md**: Each package has its own guidance
+3. **Run package commands**: `composer test`, `npm run dev`
+
+Or from the workspace root, change the active package in `.core/workspace.yaml`.
+
+## Dependencies
+
+See `repos.yaml` for the full dependency tree. Key relationships:
+- `core-php` has no dependencies (foundation)
+- `core-tenant`, `core-admin`, `core-api`, `core-mcp` depend on `core-php`
+- Products depend on `core-php` and `core-tenant`
+- `core-agentic` depends on `core-php`, `core-tenant`, and `core-mcp`
+
+## Tips
+
+1. **Always prefer `core` commands** over raw git/composer when working across repos
+2. **Check `core health`** before starting work to see repo status
+3. **Use `core impact`** before changing shared packages
+4. **Each package has its own CLAUDE.md** with specific guidance
diff --git a/.core/workspace.yaml b/.core/workspace.yaml
new file mode 100644
index 0000000..5d188e0
--- /dev/null
+++ b/.core/workspace.yaml
@@ -0,0 +1,24 @@
+# Host UK Workspace Configuration
+# This file configures the core CLI workspace behaviour
+version: 1
+
+# Active package for `core php dev`, `core php test`, etc.
+# When running from the workspace root, commands target this package
+active: core-php
+
+# Default package types for `core setup`
+# Only these types are cloned by default (override with --only flag)
+default_only:
+  - foundation
+  - module
+
+# Paths
+packages_dir: ./packages
+
+# Workspace-level settings
+settings:
+  # Auto-suggest core commands when using raw git/composer
+  suggest_core_commands: true
+
+  # Show package status in prompt (if shell integration enabled)
+  show_active_in_prompt: true
diff --git a/.gitignore b/.gitignore
index 596eedc..01a68d6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,8 +2,8 @@
 packages/*
 !packages/.gitkeep
 
-# Core CLI cache (transient data)
-.core/
+# Core CLI cache (transient data, not config)
+.core/cache/
 
 # IDE
 .idea/
diff --git a/CLAUDE.md b/CLAUDE.md
index 3ee95ff..c829041 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,30 +6,75 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 This is the **developer workspace orchestrator** for Host UK - a federated monorepo containing 18 Laravel packages. This repo contains only configuration and setup scripts; actual code lives in `packages/core-*/`, each with its own CLAUDE.md.
 
+For coding standards, architecture patterns, and Laravel-specific guidance, see the parent `/Users/snider/Code/host-uk/CLAUDE.md`.
+
+## .core/ Folder System
+
+This workspace uses a `.core/` folder for configuration and Claude Code integration:
+
+```
+.core/
+├── workspace.yaml           # Active package, paths, settings
+├── plugin/
+│   ├── plugin.json          # Claude Code manifest
+│   ├── skills/              # Context-aware skills
+│   │   ├── workspace.md     # Multi-repo navigation
+│   │   ├── switch-package.md
+│   │   └── package-status.md
+│   └── hooks/               # Command hooks
+│       └── prefer-core.sh   # Suggest core CLI commands
+└── docs/
+    └── core-folder-spec.md  # Full .core/ specification
+```
+
+### Active Package
+
+The **active package** in `.core/workspace.yaml` determines where unified commands run:
+
+```yaml
+active: core-php  # Commands like `core php test` target this package
+```
+
+When working from the workspace root, change this to work on a different package without navigating directories.
+
+### Skills
+
+Skills in `.core/plugin/skills/` provide context-aware guidance:
+- **workspace.md** - Multi-repo navigation and commands
+- **switch-package.md** - How to change the active package
+- **package-status.md** - Checking status across repos
+
+### Specification
+
+See `.core/docs/core-folder-spec.md` for the full specification that each package should follow.
+
 ## Initial Setup
 
 ```bash
-# One-liner (macOS/Linux)
+# macOS/Linux
 git clone git@github.com:host-uk/core-devops.git && cd core-devops && make setup
 
-# Or step by step
-make install-deps       # Install go, gh, php, node, pnpm
-make install-core       # Build/install core CLI to ~/.local/bin
-make clone              # Clone all repos into packages/
+# Windows (PowerShell as Admin)
+.\scripts\install-deps.ps1 && .\scripts\install-core.ps1 && core setup
 ```
 
+Environment variables for `install-core.sh`:
+- `INSTALL_DIR` - Binary location (default: `~/.local/bin`)
+- `BUILD_FROM_SOURCE` - `true`, `false`, or `auto` (default: `auto`, tries binary then builds)
+
 ## Commands
 
+### Workspace-level (from root)
 ```bash
-# Environment
-make setup              # Full setup (deps + core + clone)
-core doctor             # Check environment (requires: git, gh, php 8.3+, composer, node 20+, pnpm)
+# Setup & diagnostics
+make setup              # Full setup (deps + core CLI + clone repos)
+core doctor             # Check environment health
 core doctor --fix       # Attempt to fix issues
 
 # Multi-repo workflow
 core health             # Quick status summary
 core work               # Full workflow: status → commit → push
-core work --status      # Status table only (no commit/push)
+core work --status      # Status table only
 core commit             # Claude-assisted commits for dirty repos
 core commit --all       # Commit all without prompting
 core push               # Push repos with unpushed commits
@@ -38,38 +83,66 @@ core pull               # Pull repos that are behind
 # GitHub integration (requires gh CLI)
 core issues             # List open issues across repos
 core issues --assignee @me
-core reviews            # List PRs with review status
+core reviews            # List PRs needing review
 core ci                 # GitHub Actions workflow status
 
-# Analysis
+# Dependency analysis
 core impact core-php    # Show what depends on core-php
 ```
 
-## Working on Packages
-
+### Active package (from root)
 ```bash
-cd packages/core-php
-composer install
-composer test           # Run Pest tests
-composer lint           # Fix code style (Pint)
-npm run dev             # Vite dev server (if has frontend)
+core php test           # Run Pest tests in active package
+core php lint           # Run Pint linter in active package
+core php dev            # Start Vite dev server
 ```
 
-## Package Types (repos.yaml)
+### Direct package work
+```bash
+cd packages/core-php
+composer install && composer test           # Run Pest tests
+composer test -- --filter=ClassName         # Single test
+./vendor/bin/pint --dirty                   # Format changed files
+```
 
-| Type | Examples | Purpose |
-|------|----------|---------|
-| foundation | core-php | Base framework (no dependencies) |
-| module | core-tenant, core-admin, core-api, core-mcp | Infrastructure services |
-| product | core-bio, core-social, core-analytics | User-facing applications |
-| template | core-template | Starter for new projects |
-| meta | core-devops | This workspace repo |
+## Package Switching Workflow
 
-## This Is a Workspace, Not Code
+To work on a different package without navigating:
 
-Don't add code here. All actual development happens in `packages/core-*/`.
+1. Edit `.core/workspace.yaml`:
+   ```yaml
+   active: core-tenant
+   ```
 
-This repo manages:
+2. Run commands from workspace root:
+   ```bash
+   core php test    # Now runs in core-tenant
+   ```
+
+3. Read the package's CLAUDE.md:
+   ```bash
+   cat packages/core-tenant/CLAUDE.md
+   ```
+
+## Package Types
+
+Defined in `repos.yaml`:
+- **foundation**: `core-php` - base framework, no dependencies
+- **module**: `core-tenant`, `core-admin`, `core-api`, `core-mcp` - infrastructure
+- **product**: `core-bio`, `core-social`, etc. - user-facing apps
+- **template**: `core-template` - starter for new projects
+- **meta**: `core-devops` - this workspace repo
+
+## Troubleshooting
+
+- **"core: command not found"** → `make install-core` (builds from https://github.com/host-uk/core)
+- **"gh: command not found"** → `brew install gh && gh auth login`
+- **Clone failures** → `ssh -T git@github.com` to verify SSH keys
+
+## This Repo's Scope
+
+Don't add application code here. This repo only contains:
 - `repos.yaml` - Package registry with dependencies
-- `packages/` - Cloned repositories (git-ignored)
-- `scripts/` - Setup scripts for macOS/Linux/Windows
+- `scripts/` - Cross-platform setup scripts (install-deps, install-core)
+- `Makefile` - Setup orchestration
+- `.core/` - Workspace configuration and Claude Code integration
diff --git a/README.md b/README.md
index 1ace982..dcbab24 100644
--- a/README.md
+++ b/README.md
@@ -1,96 +1,158 @@
 # Host UK Developer Workspace
 
-This repository bootstraps a complete Host UK development environment.
+This repository is the **unified entry point** for Host UK development. One command sets up your entire environment.
 
 ## Quick Start
 
-### One-liner (macOS/Linux)
 ```bash
 git clone git@github.com:host-uk/core-devops.git && cd core-devops && make setup
 ```
 
-### Step by step
+**Windows (PowerShell as Admin):**
+```powershell
+git clone git@github.com:host-uk/core-devops.git; cd core-devops; .\scripts\install-deps.ps1; .\scripts\install-core.ps1; core setup
+```
+
+## What Happens
+
+`make setup` does three things:
+
+1. **Installs dependencies** - PHP 8.3+, Composer, Node 20+, pnpm, GitHub CLI
+2. **Installs the `core` CLI** - Multi-repo management tool
+3. **Clones all packages** - Into `packages/` (foundation and modules by default)
+
+After setup, run `core doctor` to verify everything is working.
+
+## What's Next
+
+You're now ready to develop. The workspace starts with `core-php` as the active package.
+
 ```bash
-# 1. Clone this repo
-git clone git@github.com:host-uk/core-devops.git
-cd core-devops
+# Check your environment
+core doctor
 
-# 2. Install dependencies and core CLI
-make setup
+# See workspace status
+core health
 
-# Or manually:
-./scripts/install-deps.sh   # Install go, gh, php, node, etc.
-./scripts/install-core.sh   # Build and install core CLI
+# Run tests in the active package (core-php)
+core php test
 
-# 3. Start developing
+# Switch to a different package
+# Edit .core/workspace.yaml and change "active: core-tenant"
+```
+
+To work directly in a package:
+```bash
 cd packages/core-php
 composer install
+composer test
 ```
 
-### Windows (PowerShell as Admin)
-```powershell
-git clone git@github.com:host-uk/core-devops.git
-cd core-devops
-.\scripts\install-deps.ps1   # Install via Chocolatey
-.\scripts\install-core.ps1   # Build and install core CLI
-core setup                   # Clone all repos
-```
-
-## Prerequisites
-
-Run `core doctor` to check your environment. You'll need:
-
-- **Git** - Version control
-- **GitHub CLI** (`gh`) - For issues, PRs, CI status
-- **PHP 8.3+** - Laravel packages
-- **Composer** - PHP dependencies
-- **Node.js 20+** - Frontend builds
-- **pnpm** - Package manager (preferred over npm)
-
-Optional but recommended:
-- **Claude Code** - AI-assisted development
-- **Docker** - For FrankenPHP runtime
-
 ## Commands
 
+### Workspace-level
 ```bash
-core setup              # Clone all repos into packages/
-core setup --only foundation,module  # Clone specific types
-core doctor             # Check environment health
-core doctor --fix       # Attempt to fix issues
+core health             # Status summary: "18 repos │ clean │ synced"
+core work               # Full workflow: status → commit → push
+core work --status      # Status table only
+core commit             # Claude-assisted commits for dirty repos
+core push               # Push repos with unpushed commits
+core pull               # Pull repos that are behind
+```
 
-# Once set up, standard core commands work:
-core health             # Status summary
-core work               # Commit and push workflow
-core issues             # View GitHub issues
+### Active package
+```bash
+core php test           # Run Pest tests
+core php lint           # Run Pint linter
+core php dev            # Start Vite dev server
+```
+
+### GitHub integration
+```bash
+core issues             # Open issues across repos
+core issues --assignee @me
+core reviews            # PRs needing review
+core ci                 # GitHub Actions status
+```
+
+### Analysis
+```bash
+core impact core-php    # Show what depends on core-php
 ```
 
 ## Structure
 
 ```
 core-devops/
+├── .core/              # Workspace configuration
+│   ├── workspace.yaml  # Active package, paths
+│   └── plugin/         # Claude Code integration
 ├── packages/           # Cloned repositories (git-ignored)
-│   ├── core-php/
-│   ├── core-tenant/
+│   ├── core-php/       # Foundation framework
+│   ├── core-tenant/    # Multi-tenancy
+│   ├── core-admin/     # Admin panel
 │   └── ...
-├── repos.yaml          # Package registry
-└── README.md
+└── repos.yaml          # Package registry
 ```
 
-## Updating
+## Prerequisites
 
+Run `core doctor` to check your environment. Required:
+
+- **Git** - Version control
+- **GitHub CLI** (`gh`) - Issues, PRs, CI status
+- **PHP 8.3+** - Laravel packages
+- **Composer** - PHP dependencies
+- **Node.js 20+** - Frontend builds
+- **pnpm** - Package manager
+
+Optional:
+- **Claude Code** - AI-assisted development
+- **Docker** - For FrankenPHP runtime
+
+## Package Types
+
+Defined in `repos.yaml`:
+
+| Type           | Packages                                                   | Description                      |
+|----------------|------------------------------------------------------------|---------------------------------|
+| **foundation** | `core-php`                                                 | Base framework, zero dependencies |
+| **module**     | `core-tenant`, `core-admin`, `core-api`, `core-mcp`, etc.  | Infrastructure                  |
+| **product**    | `core-bio`, `core-social`, `core-analytics`, etc.          | User-facing apps                |
+| **template**   | `core-template`                                            | Starter for new projects        |
+| **meta**       | `core-devops`                                              | This workspace repo             |
+
+By default, `core setup` clones foundation and module packages. To clone specific types:
 ```bash
-core pull               # Pull updates for all repos
-core pull --all         # Pull even if not behind
+core setup --only foundation,module,product
 ```
 
 ## Troubleshooting
 
 **"core: command not found"**
-Install the Core CLI from https://github.com/Snider/Core
+```bash
+make install-core
+```
 
 **"gh: command not found"**
-Install GitHub CLI: `brew install gh` then `gh auth login`
+```bash
+brew install gh && gh auth login
+```
 
 **Clone failures**
-Check your SSH keys: `ssh -T git@github.com`
+```bash
+ssh -T git@github.com  # Verify SSH keys
+```
+
+**Missing dependencies**
+```bash
+core doctor --fix
+```
+
+## Documentation
+
+- **This repo's CLAUDE.md** - Guidance for Claude Code in the workspace
+- **repos.yaml** - Full package registry with dependencies
+- **`.core/docs/core-folder-spec.md`** - Specification for `.core/` folders
+
+Each package in `packages/` has its own CLAUDE.md with package-specific guidance.