docs: align with satware AG best practices

- Delete deprecated CLAUDE.md
- Create root-level AGENTS.md for AI assistant guidance
- Create SDD constitution in .specify/memory/constitution.md
- Align documentation with PARA structure (docs/product/project-brief.md, docs/tech/stack.md, docs/plans/)
- Add standardized YAML frontmatter to all documentation files
- Update README.md with saTway branding and structure

README.md

@@ -1,40 +1,65 @@
-# saTway DevOps - mw-pfeddersheim-workstation
+---
+description: >-
+  Infrastructure-as-Code and maintenance repository for Michael Wegener's
+  primary workstation at satware AG (Pfeddersheim location).
+tags:
+  - workstation
+  - ansible
+  - infrastructure-as-code
+  - linux
+  - automation
+last_updated: '2026-03-09'
+---
 
-This repository contains the infrastructure-as-code, configuration, and maintenance scripts for the **mw-pfeddersheim-workstation**.
+# saTway® Infrastructure - mw-pfeddersheim-workstation
+
+This repository manages the configuration, software stack, and maintenance scripts for Michael Wegener's primary workstation. It ensures a reproducible, secure, and optimized environment following **satware AG** best practices.
 
 ## 🚀 Quick Start
 
-To apply the current configuration to the workstation:
+To apply the current configuration or run maintenance:
 
 ```bash
-# Apply Ansible configuration
+# 1. Verify configuration with a dry run
+ansible-playbook ansible/workstation.yml --check
+
+# 2. Apply configuration locally
 ansible-playbook ansible/workstation.yml
 
-# Run maintenance
+# 3. Run automated maintenance
 bash scripts/maintenance.sh
 ```
 
-## 📂 Structure
+## 📂 Project Structure
 
-- `ansible/`: Ansible playbooks and roles for system configuration.
-- `config/`: Configuration files for various system components.
-- `docs/`: Comprehensive documentation following the satware AG PARA structure.
-- `scripts/`: System maintenance and automation scripts.
+| Directory | Purpose |
+|-----------|---------|
+| `ansible/` | Configuration-as-Code (Roles: `common`, `dev-tools`, `maintenance`) |
+| `config/` | System configuration templates (`.j2`) |
+| `docs/` | PARA-structured documentation (`product`, `adr`, `learnings`, `tech`) |
+| `scripts/` | Maintenance and automation scripts |
 
 ## 🛠 Software Stack
 
-The workstation is equipped with the following core tools:
-- **Languages**: Node.js 22+, Python 3.12+, PHP 8.4
-- **DevOps**: Docker, Ansible, Terraform (planned)
-- **Editors**: IntelliJ IDEA, VS Code
-- **Shell**: Bash, Git
+- **Languages**: Node.js 22 LTS, Python 3.12+, PHP 8.4
+- **Automation**: Ansible, Docker
+- **Environment**: Manjaro/Arch Linux, Bash
 
-## 📜 Principles
+## 📜 Core Principles
 
-- **Baby Steps™**: Small, verifiable changes.
-- **Zero-Trust**: No secrets in the repository, use Ansible Vault or secret managers.
-- **TDD**: Write tests for scripts using `bats` (planned).
+- **Baby Steps™**: All changes are small, atomic, and verifiable.
+- **Spec-Driven Development**: Intent-first development with explicit documentation.
+- **Zero-Trust**: Secrets are managed via `ansible-vault` or environment variables; never committed raw.
 
-## 📄 License
+## 📄 Documentation
 
-Proprietary - satware AG. All rights reserved.
+Comprehensive documentation is available in the `docs/` directory:
+- [Project Brief](docs/product/project-brief.md)
+- [Setup Guide](docs/tech/setup.md)
+- [Software Stack](docs/tech/stack.md)
+- [Software Audit](docs/tech/current-software-audit.md)
+- [Decision Records](docs/adr/0001-use-ansible-for-configuration.md)
+
+---
+
+© 2026 satware AG. All rights reserved.