docs: add website working contract (#247)

## Summary
- add a repo-truth-based website working contract for `apps/website`
- link the new contract from the workspace README
- document the current minimal website/platform coordination boundaries

## Testing
- not run (documentation-only changes)

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #247

README.md

@@ -12,6 +12,9 @@ ## Multi-App Topology
 - repo root: workspace manifests, documentation, scripts, editor tooling, and `docker-compose.yml`
 - `./scripts/platform-sail`: platform-only compatibility helper for tooling that cannot set `cwd`
 
+Website-track guardrails for independent evolution live in
+[`docs/strategy/website-working-contract.md`](docs/strategy/website-working-contract.md).
+
 ## Official Root Commands
 
 - Install workspace-managed JavaScript dependencies: `corepack pnpm install`

docs/strategy/website-working-contract.md

@@ -0,0 +1,237 @@
+# Website Working Contract
+
+> Guardrails for evolving `apps/website` as an independently evolvable track in the current repository.
+> This document is repo-truth-based and describes the currently verified state, not a speculative future architecture.
+
+**Last reviewed**: 2026-04-18
+
+---
+
+## 1. Purpose
+
+`apps/website` is currently treated as an independently evolvable website track.
+
+This contract is based on the current repository state:
+
+- no verified runtime coupling to `apps/platform`
+- no verified shared DTO, enum, API, or auth contracts
+- current relevant coupling is primarily through root scripts, the pnpm workspace, the website package name, `WEBSITE_PORT`, and `apps/platform/tests/Feature/WorkspaceFoundation/PlatformWorkspaceCompatibilityTest.php`
+
+Therefore, website work should be planned and implemented as technically independent by default unless a known minimal contract is being changed.
+
+## 2. Scope
+
+This working contract applies to:
+
+- `apps/website/**`
+- root files only insofar as they directly define or preserve website-facing workspace contracts
+
+This document does not grant implicit approval to introduce new coupling to:
+
+- `apps/platform`
+- shared runtime APIs
+- shared auth or session behavior
+- shared domain models
+- shared packages
+
+Such coupling must be introduced deliberately and treated as a new explicit contract.
+
+## 3. Current Repo-Based Statement
+
+At the current verified repo state, `apps/website` is:
+
+- a small static Astro application
+- built from local layout, local page, and local CSS files
+- without verified platform runtime dependency
+- without verified shared workspace packages
+- without verified platform API usage
+- without verified auth or session sharing
+
+The current real technical coupling is concentrated in:
+
+- `package.json`
+- `pnpm-workspace.yaml`
+- `apps/website/package.json`
+- `README.md`
+- `apps/platform/tests/Feature/WorkspaceFoundation/PlatformWorkspaceCompatibilityTest.php`
+
+## 4. Freely Changeable Without Special Coordination
+
+The following changes are currently treated as website-internal and are generally free to make as long as they do not create new outward-facing contracts.
+
+### Content and Structure
+
+- copy
+- headlines
+- messaging
+- CTA text
+- page sections
+- HTML structure inside the website
+
+### UI and Frontend
+
+- styling in `src/styles/global.css`
+- layout changes in `src/layouts/BaseLayout.astro`
+- additional components inside `apps/website`
+- additional pages under `src/pages`
+- additional layouts
+- additional local assets
+
+### Astro-Local Evolution
+
+- expanding page structure
+- refactoring inline markup into components
+- app-local reorganization inside `apps/website`
+- local SEO, meta, robots, and favicon updates
+
+### Usually Non-Critical When Kept Local
+
+- new website-only dependencies
+- app-local build or styling improvements
+- app-local content structures
+
+## 5. Changes Requiring Coordination
+
+The following changes must not happen silently because they touch real existing contracts in the current repository.
+
+### Hard Minimal Contracts
+
+- changing the package name `@tenantatlas/website`
+- changing the root script names for website flows
+- changing the `WEBSITE_PORT` convention
+- changing workspace membership via `apps/*`
+- moving `apps/website` out of the current workspace pattern
+
+### Repo and Tooling Contracts
+
+- changes that break `pnpm --filter @tenantatlas/website ...`
+- changes that break the root `dev:website` or `build:website` workflows
+- changes that break `PlatformWorkspaceCompatibilityTest.php`
+- changes to root scripts when the website is expected to remain reachable through root commands
+
+### New Technical Couplings
+
+- introducing API calls to `apps/platform`
+- introducing shared DTOs, enums, or payload contracts
+- introducing shared auth or session mechanics
+- introducing shared packages as a required dependency
+- introducing shared content or asset sources
+- introducing a shared runtime deployment model
+
+## 6. Silent Assumptions That Are Not Allowed
+
+For website work, the following assumptions are explicitly disallowed:
+
+- monorepo membership does not automatically mean technical coupling
+- `apps/platform` is not automatically part of website frontend scope
+- Filament or Livewire changes are not automatically website-relevant
+- shared product domain does not automatically imply a shared technical contract
+- future integrations must not be pre-assumed when they do not exist in the repo
+
+## 7. Rule for New Couplings
+
+New coupling between website and platform is allowed only when it is introduced as an explicit new contract.
+
+Before implementation, the following must be made clear:
+
+- which coupling is being introduced
+- where it is defined in the repo
+- whether it is runtime, build, deploy, or convention coupling
+- what impact it has on independent evolution of `apps/website`
+- what stability guarantee is expected going forward
+
+Without that explicit decision, the default rule is:
+
+**Do not introduce a new coupling.**
+
+## 8. Review Rule for Website PRs
+
+A change in `apps/website` is uncritical by default when all of the following can be answered with `Yes`:
+
+- Does the package name `@tenantatlas/website` remain unchanged?
+- Do the root scripts remain functionally compatible?
+- Does `WEBSITE_PORT` remain unchanged?
+- Does workspace membership through `apps/*` remain intact?
+- Is no new dependency on `apps/platform` introduced?
+- Is no new API, auth, DTO, or shared-package contract introduced?
+- Does the change stay entirely inside `apps/website`?
+
+If any answer is `No`, the change is coordination-required.
+
+## 9. Change Classes
+
+### Class A — Free
+
+Pure website change with no new outward-facing contract.
+
+Examples:
+
+- new landing page
+- refactor of `index.astro`
+- new components
+- CSS restructuring
+- local SEO changes
+
+### Class B — Cautious
+
+Change likely remains local but touches website build or dev behavior.
+
+Examples:
+
+- adjusting Astro configuration
+- adding website dependencies
+- larger structural changes in `src/`
+
+Normal website review is usually sufficient.
+
+### Class C — Coordination-Required
+
+Change touches root, workspace, or test contracts, or introduces new coupling.
+
+Examples:
+
+- renaming the package
+- changing scripts
+- changing the port convention
+- changing the workspace pattern
+- integrating a platform API
+- introducing shared types
+
+These changes require explicit coordination.
+
+## 10. Operational Summary
+
+Yes: `apps/website` may currently be developed as its own frontend and website track.
+
+Condition: the known minimal contracts stay stable:
+
+- `@tenantatlas/website`
+- root scripts
+- `WEBSITE_PORT`
+- `apps/*`
+- compatibility with `PlatformWorkspaceCompatibilityTest.php`
+
+Not automatically part of website scope:
+
+- changes in `apps/platform`
+
+Introduce only deliberately:
+
+- any new runtime, API, auth, shared-package, or DTO coupling
+
+## 11. Evidence Anchors
+
+This contract is grounded in the current repo state represented by these files:
+
+- `apps/website/package.json`
+- `apps/website/astro.config.mjs`
+- `apps/website/src/pages/index.astro`
+- `apps/website/src/layouts/BaseLayout.astro`
+- `apps/website/src/styles/global.css`
+- `package.json`
+- `pnpm-workspace.yaml`
+- `README.md`
+- `apps/platform/tests/Feature/WorkspaceFoundation/PlatformWorkspaceCompatibilityTest.php`
+- `docker-compose.yml`
+
+If these files change materially, this contract should be revalidated against the current checkout.