# Contract: Workspace Command Model

## Purpose

Define the official repo-root and app-local commands for the first multi-app TenantAtlas workspace.

## Ownership Rule

- Root commands orchestrate.
- App-local commands execute.
- The root must never re-implement platform or website runtime logic.

## Official Root Commands

| Command | Responsibility | Notes |
|---------|----------------|-------|
| `pnpm install` | Install workspace JavaScript dependencies | Root entry for workspace-managed JS dependencies |
| `pnpm dev:platform` | Start the platform app | Delegates to the existing platform Sail flow |
| `pnpm dev:website` | Start the website app | Runs the Astro dev server from `apps/website` |
| `pnpm dev` | Start platform + website for parallel local development | Platform may background via Sail while website dev stays foreground |
| `pnpm build:website` | Build the website app | Produces website-only artifacts |
| `pnpm build:platform` | Build platform frontend assets | Delegates into `apps/platform` and preserves existing Laravel asset flow |

## Supported Port Override Path

- If the platform HTTP or Vite ports are already in use, the supported override path is environment-based: set `APP_PORT` and or `VITE_PORT` before invoking the root platform command, and pass the same variables through the app-local Sail flow when using `apps/platform` directly.
- If the website port is already in use, the supported override path is environment-based: set `WEBSITE_PORT` before invoking the root website or parallel-dev command, and pass the equivalent `--port` flag through the app-local `apps/website` Astro dev command.
- The root `pnpm dev:website` and `pnpm dev` scripts must forward `WEBSITE_PORT` to the Astro dev server.
- The supported override path must be documented in the root README and validated in smoke checks.

## Valid App-local Commands

### Platform

- `cd apps/platform && ./vendor/bin/sail up -d`
- `cd apps/platform && ./vendor/bin/sail stop`
- `cd apps/platform && ./vendor/bin/sail pnpm dev`
- `cd apps/platform && ./vendor/bin/sail pnpm build`
- `cd apps/platform && ./vendor/bin/sail artisan test --compact`

### Website

- `cd apps/website && pnpm dev`
- `cd apps/website && pnpm build`

## Compatibility Helpers

- `./scripts/platform-sail ...` remains valid for tooling that cannot set `cwd`.
- This helper is platform-specific in this slice and must not be generalized into a multi-app runner yet.

## Tooling Scope Rules

- `.vscode/mcp.json` and `opencode.json` remain platform-only because Boost MCP is Laravel-specific.
- VS Code tasks may expose official root entry tasks for platform, website, and parallel dev, but must not imply a second hidden workflow.

## Invariants

- The platform remains Sail-first.
- The website remains independent of Sail, Laravel, Blade, Filament, and platform sessions.
- Composer remains app-local PHP dependency management for `apps/platform`.
- pnpm is the one official JavaScript workspace/package-manager standard.
- No root command may require the website build to start the platform or vice versa.

## Failure Conditions

- A root command is undocumented but treated as official.
- A website command depends on platform runtime state.
- A platform command requires undocumented root-only state.
- Root tooling suggests npm for one app and pnpm for another as equal official workflows.
- Port conflicts exist but no documented, supported override path is available for the platform or website commands.