Establish Phase 1 Atlas infrastructure repository

.gitignore

@@ -0,0 +1,104 @@
+# Secrets and environment files
+.env
+.env.*
+!.env.example
+!.env.*.example
+*.secret
+*.secrets
+secrets/
+credentials/
+local-secrets/
+
+# Private keys and certificates
+*.key
+*.pem
+*.p12
+*.pfx
+*.crt
+*.csr
+*.jks
+id_rsa
+id_rsa.*
+id_ed25519
+id_ed25519.*
+*_rsa
+*_rsa.*
+*_ed25519
+*_ed25519.*
+
+# Local overrides
+*.local
+*.local.*
+local/
+overrides/
+*.override
+*.override.*
+
+# Logs
+*.log
+logs/
+log/
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+*.temp
+*.swp
+*.swo
+*~
+.cache/
+
+# Build outputs and dependencies
+bin/
+obj/
+build/
+out/
+dist/
+publish/
+coverage/
+node_modules/
+.next/
+.nuxt/
+
+# Deployment artefacts and archives
+artifacts/
+artefacts/
+deployments/
+releases/
+*.zip
+*.tar
+*.tar.gz
+*.tgz
+*.7z
+
+# Backup artefacts and database dumps
+/backups/
+/backup/
+*.bak
+*.trn
+*.bacpac
+*.dacpac
+*.dump
+*.sql.gz
+*.sql.zip
+
+# Package caches
+.npm/
+.pnpm-store/
+.yarn/
+.pip-cache/
+vendor/cache/
+packages/
+*.deb
+*.rpm
+
+# IDE and editor metadata
+.vscode/
+.idea/
+*.code-workspace
+
+# OS metadata
+.DS_Store
+Thumbs.db
+desktop.ini

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this repository will be documented in this file.
+
+## Unreleased
+
+- Created the Phase 1 repository structure for `atlas`.
+- Added baseline documentation for architecture, operating model, rebuild, disaster recovery, and server standards.
+- Added the first Architecture Decision Record.

README.md

@@ -0,0 +1,110 @@
+# Atlas AI Development Server
+
+Atlas is a dedicated AI development server used as the primary Linux host for source code, automation, development tooling, operational scripts, and future application deployment work.
+
+This repository is the authoritative infrastructure and operations source for Atlas. Its long-term purpose is to make the server rebuildable from a clean Ubuntu installation using documented, version-controlled, idempotent automation.
+
+## Current Server Summary
+
+The following facts are established for the current server:
+
+- Hostname: `atlas`
+- Operating system: Ubuntu 26.04 LTS
+- Static IP address: `192.168.10.10`
+- CPU: AMD Ryzen 7 2700
+- Memory: 16 GB RAM
+- OS storage: SSD using full-disk LVM, mounted at `/`
+- SQL data volume: SSD mounted at `/sql`
+- Development volume: SSD mounted at `/srv`
+- Repository location: `/srv/repos/AI-Development-Server`
+- Git remote: `git@git.catherinelynwood.com:atlas-bot/AI-Development-Server.git`
+
+Do not add unverified server details to this repository. Use `TODO: Confirm during the relevant implementation phase.` where information is not yet established.
+
+## Repository Purpose
+
+This repository will contain:
+
+- Atlas architecture and operating documentation.
+- Server standards for scripts, services, configuration, deployment, and change control.
+- Installation automation.
+- Configuration templates.
+- Operational scripts.
+- Smoke tests and validation checks.
+- Recovery and rebuild runbooks.
+- Architecture Decision Records.
+- Build history.
+
+It must not contain secrets, passwords, tokens, private keys, live credentials, database backups, generated deployment artefacts, or local machine state.
+
+## Design Principles
+
+- Git is the source of truth for infrastructure and operational intent.
+- Changes should be documented before they are automated.
+- Installation scripts must be idempotent and safe to rerun.
+- Manual server changes should be reduced over time and recorded when they occur.
+- Source, build artefacts, deployed applications, data, backups, and temporary files must remain separate.
+- Secrets must live outside the repository.
+- Planned components must not be documented as installed until verified.
+
+## Repository Layout
+
+```text
+.
+├── README.md
+├── SERVER-STANDARDS.md
+├── docs/
+│   ├── ARCHITECTURE.md
+│   ├── BUILD-LOG.md
+│   ├── REBUILD-GUIDE.md
+│   ├── DISASTER-RECOVERY.md
+│   ├── OPERATING-MODEL.md
+│   └── adr/
+├── install/
+├── config/
+├── scripts/
+├── tests/
+├── templates/
+└── .gitignore
+```
+
+Directory-level README files explain what belongs in each working area.
+
+## Future Installation Model
+
+Future installation scripts will live under `install/`. They will be ordered, idempotent Bash scripts, for example:
+
+```text
+install/01-base-tools.sh
+install/02-dotnet.sh
+install/03-sqlserver.sh
+install/04-nginx.sh
+install/05-docker.sh
+```
+
+These scripts do not exist yet. Until they do, rebuild steps remain manual and are documented in [docs/REBUILD-GUIDE.md](docs/REBUILD-GUIDE.md).
+
+## Change Control
+
+- Plan architecture and standards changes before implementation.
+- Review diffs before committing.
+- Run relevant validation before commit.
+- Do not commit without explicit approval.
+- Keep commits focused on one infrastructure outcome.
+- Record meaningful operational changes in [docs/BUILD-LOG.md](docs/BUILD-LOG.md).
+
+## Roadmap Summary
+
+- Phase 1: Establish repository structure, standards, architecture documentation, rebuild guidance, disaster recovery guidance, operating model, and ADR process.
+- Future phases: Add idempotent installation scripts, configuration templates, operational scripts, smoke tests, backup automation, restore automation, deployment automation, and monitoring.
+
+## Security Warning
+
+Never commit secrets or credentials. This includes `.env` files, passwords, tokens, private keys, certificates, SQL backups, Codex authentication material, deployment credentials, and backup encryption keys.
+
+Use templates, examples, placeholder names, and documented environment variable names instead.
+
+## Rebuild and Recovery
+
+- Rebuild procedure: [docs/REBUILD-GUIDE.md](docs/REBUILD-GUIDE.md)
+- Disaster recovery: [docs/DISASTER-RECOVERY.md](docs/DISASTER-RECOVERY.md)

SERVER-STANDARDS.md

@@ -0,0 +1,179 @@
+# Server Standards
+
+These standards apply to infrastructure documentation, installation scripts, operational scripts, configuration templates, tests, and manual server changes for Atlas.
+
+Unknowns must be written exactly as `TODO: Confirm during the relevant implementation phase.`
+
+## Bash Script Conventions
+
+- Use Bash for repository-managed server automation unless a better tool is explicitly adopted by an ADR.
+- Start executable scripts with `#!/usr/bin/env bash`.
+- Use `set -Eeuo pipefail`.
+- Prefer explicit named variables over positional parameters.
+- Quote variable expansions unless word splitting is intentional.
+- Keep functions small and named by behaviour.
+- Use long option names where they improve readability.
+- Avoid hidden dependencies on the current working directory. Resolve paths explicitly.
+- Place shared helpers only when repeated logic justifies them.
+
+## Idempotency
+
+- Scripts must be safe to run more than once.
+- Check current state before making changes.
+- Prefer create-or-update behaviour over delete-and-recreate behaviour.
+- Do not assume users, packages, directories, mounts, services, firewall rules, or configuration files are absent.
+- Print a clear message when a step is already satisfied.
+- Avoid overwriting local state unless the script owns that file and has a documented rollback path.
+
+## Error Handling
+
+- Fail early when prerequisites are missing.
+- Use meaningful error messages that identify the failed operation.
+- Do not continue after a failed critical step.
+- Use traps when cleanup or failure context is useful.
+- Validate inputs before making changes.
+- Treat unset variables as errors.
+
+## Logging
+
+- Print concise progress messages.
+- Use consistent prefixes: `[INFO]`, `[WARN]`, `[ERROR]`, `[OK]`.
+- Do not print secrets, tokens, passwords, connection strings, private keys, or certificate material.
+- Long-term logs must be stored outside this repository.
+- Repository scripts may write temporary logs only under documented temporary paths and must clean them up where practical.
+
+## Exit Codes
+
+- `0`: success.
+- `1`: general failure.
+- `2`: invalid arguments or missing required input.
+- `3`: unmet prerequisite.
+- `4`: validation failed.
+- `5`: unsafe state detected.
+
+## File Ownership and Permissions
+
+- Repository files should be owned by the dedicated development user.
+- Use executable permissions only for scripts intended to be run directly.
+- Use root ownership only for system files that require it.
+- Do not change ownership recursively outside documented paths.
+- Secrets outside the repository must use the narrowest practical permissions.
+- Templates in the repository must not contain live secrets.
+
+## Configuration Locations
+
+- Repository-managed templates belong under `config/` or `templates/`.
+- Generated or live service configuration belongs in the service's normal system location, usually under `/etc`, and should be produced from repository templates where practical.
+- Local overrides must not be committed.
+- Application-specific paths must not be locked in until the relevant implementation phase confirms them.
+
+## Service Naming
+
+- Use clear, stable service names.
+- Prefer names that identify the application or function rather than the implementation detail.
+- Prefix Atlas-specific helper services consistently when a naming convention is established.
+- Avoid renaming services without a migration and rollback note.
+- Service naming convention: `TODO: Confirm during the relevant implementation phase.`
+
+## systemd Conventions
+
+- Store systemd unit templates under `config/systemd/` or `templates/` when introduced.
+- Install live units under the appropriate systemd directory only through documented scripts.
+- Run `systemctl daemon-reload` after unit changes.
+- Enable services only when the intended boot behaviour is documented.
+- Prefer environment files outside the repository for secret-bearing configuration.
+- Include validation steps for service status and logs.
+
+## nginx Conventions
+
+- Store nginx templates under `config/nginx/` or `templates/` when introduced.
+- Do not commit live TLS private keys or certificates.
+- Validate nginx configuration before reloads.
+- Reload nginx only after successful validation.
+- Keep reverse proxy rules explicit and reviewed.
+- Public DNS, TLS, and exposure policy: `TODO: Confirm during the relevant implementation phase.`
+
+## SQL Server Data Locations
+
+- `/sql` is the intended SQL data volume.
+- SQL Server data, logs, and backups must not be stored in this repository.
+- SQL Server paths must be confirmed during the SQL Server implementation phase before automation is created.
+- Backup destination, retention, encryption, and restore validation are not yet established.
+
+## Repository Locations
+
+- `/srv` is the primary development volume.
+- Git repositories should live under `/srv/repos`.
+- This infrastructure repository lives at `/srv/repos/AI-Development-Server`.
+- Do not assume application repository names or paths until they are confirmed.
+
+## Deployment Locations
+
+- Deployment locations must be outside this infrastructure repository.
+- Deployed applications should be separated from source repositories and build artefacts.
+- Intended deployment root: `TODO: Confirm during the relevant implementation phase.`
+- Deployment scripts must document rollback and validation.
+
+## Backup Locations
+
+- Backups must not be committed.
+- Backup storage location: `TODO: Confirm during the relevant implementation phase.`
+- Backup retention: `TODO: Confirm during the relevant implementation phase.`
+- Backup encryption: `TODO: Confirm during the relevant implementation phase.`
+- Restore testing schedule: `TODO: Confirm during the relevant implementation phase.`
+
+## Temporary File Handling
+
+- Use `mktemp` for script-created temporary files and directories.
+- Clean temporary files on exit where practical.
+- Do not place temporary files in the repository unless they are intentionally version-controlled examples.
+- Never store secret-bearing temporary files in world-readable locations.
+
+## Secrets Management
+
+- Never commit live secrets, tokens, passwords, private keys, SQL backups, `.env` files, generated credentials, or Codex authentication material.
+- Use `.example`, `.template`, placeholder values, or documented environment variable names.
+- Store secret-bearing live configuration outside the repository.
+- Rotate credentials after suspected exposure.
+- Secret storage mechanism: `TODO: Confirm during the relevant implementation phase.`
+
+## Package Installation
+
+- Installation scripts must use the system package manager where practical.
+- Add third-party package repositories only when documented and justified.
+- Validate repository signing keys and sources.
+- Avoid installing packages in ad hoc scripts without recording why they are needed.
+- Do not install application dependencies globally unless required.
+
+## Version Pinning
+
+- Pin versions when reproducibility, compatibility, or security requires it.
+- Document why a version is pinned and when it should be reviewed.
+- If using latest available packages, document that choice.
+- Do not record planned component versions as installed until verified.
+
+## Testing Requirements
+
+- Add smoke tests for scripts that change services, network state, mounts, databases, deployments, or backup behaviour.
+- Tests should verify observable outcomes, not only exit codes.
+- Tests must avoid requiring secrets where practical.
+- Tests must not mutate production data unless explicitly designed and approved.
+- Run relevant tests before committing.
+
+## Documentation Requirements
+
+- Update documentation with every change that affects rebuild, operation, security, backup, restore, deployment, or architecture.
+- Update [docs/BUILD-LOG.md](docs/BUILD-LOG.md) for meaningful manual or automated infrastructure milestones.
+- Update runbooks when manual steps become automated.
+- Link related ADRs where decisions are recorded.
+- Use UK English.
+
+## Change Control
+
+- Plan substantial changes before implementation.
+- Human approval is required for architecture changes.
+- Review `git diff` before commit.
+- Do not commit without explicit approval.
+- Keep commits focused and reversible.
+- Document rollback expectations for risky changes.
+- Git rollback restores repository state only. It does not automatically undo server changes already applied.

config/README.md

@@ -0,0 +1,43 @@
+# Config
+
+This directory is for repository-managed service configuration templates and configuration examples for Atlas.
+
+## What Belongs Here
+
+- nginx templates.
+- systemd unit templates.
+- SQL Server configuration templates.
+- Non-secret example configuration.
+- Documented placeholders for environment variables.
+
+## What Must Not Be Stored Here
+
+- Live configuration containing secrets.
+- `.env` files.
+- Private keys.
+- TLS private keys or live certificates.
+- Database backups.
+- Machine-local overrides.
+
+## Naming Conventions
+
+- Use lower-case directory names.
+- Use lower-case hyphenated file names.
+- Use `.template`, `.example`, or `.sample` for files that are not live configuration.
+- Use clear placeholder names such as `CHANGE_ME` or `${ENV_VAR_NAME}`.
+
+## Expected Future Structure
+
+Current planned areas include:
+
+```text
+config/nginx/
+config/sqlserver/
+config/systemd/
+```
+
+Additional service directories may be added when those services are implemented.
+
+## Security Considerations
+
+Configuration templates must not contain live secrets. Secret-bearing live files should be stored outside the repository and referenced by documented paths or environment variable names.

config/nginx/.gitkeep

@@ -0,0 +1 @@
+

config/sqlserver/.gitkeep

@@ -0,0 +1 @@
+

config/systemd/.gitkeep

@@ -0,0 +1 @@
+

config/templates/.gitkeep

@@ -0,0 +1 @@
+

docs/ARCHITECTURE.md

@@ -0,0 +1,193 @@
+# Atlas Architecture
+
+This document separates confirmed current architecture from planned architecture. Do not describe planned components as installed until they have been verified.
+
+## Current Architecture
+
+Atlas is a single physical development server.
+
+### Physical Server Overview
+
+- Hostname: `atlas`
+- Operating system: Ubuntu 26.04 LTS
+- Hardware model: ASUS PRIME B450-PLUS
+- CPU: AMD Ryzen 7 2700
+- Memory: 16 GB RAM
+- Architecture: x86-64
+- Role: AI development server and infrastructure automation host
+
+### Storage Layout
+
+- OS volume: SSD using LVM, mounted at `/`
+- SQL data volume: SSD mounted at `/sql`
+- Development volume: SSD mounted at `/srv`
+- Repository root: `/srv/repos`
+- Infrastructure repository: `/srv/repos/AI-Development-Server`
+
+The intended model separates operating system state, SQL data, and development data. This supports rebuild and recovery by reducing reliance on the OS volume for mutable project data.
+
+### Network Identity
+
+- Hostname: `atlas`
+- Static IP address: `192.168.10.10`
+- Default gateway: `192.168.10.1`
+- Primary network interface: `enp3s0`
+- Gitea SSH remote for this repository: `git@git.catherinelynwood.com:atlas-bot/AI-Development-Server.git`
+
+DNS, firewall, public exposure, and TLS policy are `TODO: Confirm during the relevant implementation phase.`
+
+### Repository and Source-Control Flow
+
+Git is the source of truth for repository state. Atlas holds the working copy under `/srv/repos/AI-Development-Server`, and Gitea is the remote source-control system for this infrastructure repository.
+
+Expected flow:
+
+1. Plan infrastructure changes in documentation.
+2. Implement scripts, templates, or documentation updates.
+3. Validate locally on Atlas.
+4. Review the full diff.
+5. Commit only after explicit approval.
+6. Push reviewed commits to Gitea.
+
+Branching policy is `TODO: Confirm during the relevant implementation phase.`
+
+## Planned Architecture
+
+The repository is intended to grow into the version-controlled control plane for Atlas. Planned components include:
+
+- Idempotent installation scripts under `install/`.
+- Managed configuration templates under `config/` and `templates/`.
+- Operational scripts under `scripts/`.
+- Smoke tests under `tests/`.
+- Rebuild and recovery procedures under `docs/`.
+- Architecture Decision Records under `docs/adr/`.
+
+### Intended Development Platform Components
+
+Atlas is intended to support:
+
+- Codex CLI usage.
+- Git and Git LFS workflows.
+- Node.js-based tooling where required.
+- .NET SDKs when application requirements are confirmed.
+- SQL Server when the database phase is implemented.
+- nginx when reverse proxy requirements are confirmed.
+- Docker when runtime policy is confirmed.
+- Backup, restore, monitoring, and maintenance automation.
+
+Only components verified during implementation should be recorded as installed.
+
+### Intended PlotDirector Deployment Topology
+
+PlotDirector deployment topology is not yet established.
+
+Current assumptions:
+
+- Source repositories should live under `/srv/repos`.
+- Build artefacts should be generated outside this infrastructure repository.
+- Deployed applications should be separated from source repositories.
+- SQL data should use `/sql` once SQL Server paths are confirmed.
+- nginx may act as the reverse proxy if the application is exposed over HTTP or HTTPS.
+- Docker may host one or more services if containerisation is adopted.
+
+Specific PlotDirector service names, ports, deployment paths, database names, and rollback procedures are `TODO: Confirm during the relevant implementation phase.`
+
+### Role of nginx
+
+nginx is planned as the likely local reverse proxy for HTTP and HTTPS applications. Its future responsibilities may include:
+
+- Routing requests to application services.
+- TLS termination.
+- Static file serving where appropriate.
+- Request size, timeout, and header policy.
+
+nginx installation, site layout, TLS certificate handling, and exposure rules are `TODO: Confirm during the relevant implementation phase.`
+
+### Role of SQL Server
+
+SQL Server is planned as the relational database platform for applications that require it. `/sql` is the intended data volume.
+
+SQL Server version, data paths, backup paths, service account model, authentication policy, maintenance jobs, and restore process are `TODO: Confirm during the relevant implementation phase.`
+
+### Role of Docker
+
+Docker is planned as a possible application runtime and tooling boundary. It should be introduced only after the runtime policy is documented.
+
+Docker installation method, user access policy, network policy, volume locations, image retention, and compose layout are `TODO: Confirm during the relevant implementation phase.`
+
+## Separation of Concerns
+
+The intended storage and responsibility model is:
+
+- Source repositories: `/srv/repos`
+- Infrastructure repository: `/srv/repos/AI-Development-Server`
+- Build artefacts: `TODO: Confirm during the relevant implementation phase.`
+- Deployed applications: `TODO: Confirm during the relevant implementation phase.`
+- SQL data: `/sql`
+- Backups: `TODO: Confirm during the relevant implementation phase.`
+- Temporary files: system temporary locations or script-created `mktemp` paths
+- Live secrets: outside this repository
+
+## Trust Boundaries
+
+Known trust boundaries:
+
+- Atlas local OS user accounts.
+- SSH access to Atlas.
+- SSH access from Atlas to Gitea.
+- Root-level operations performed through `sudo`.
+- Repository content versus live secret-bearing configuration.
+- SQL data on `/sql` versus source and scripts on `/srv`.
+- Future public-facing application traffic through nginx, if enabled.
+
+Unresolved trust-boundary details:
+
+- Firewall policy: `TODO: Confirm during the relevant implementation phase.`
+- Production access model: `TODO: Confirm during the relevant implementation phase.`
+- Secret storage model: `TODO: Confirm during the relevant implementation phase.`
+- Backup encryption model: `TODO: Confirm during the relevant implementation phase.`
+
+## High-Level Diagram
+
+```mermaid
+flowchart TB
+    Nick[Nick] -->|reviews plans and diffs| Git[Gitea Remote]
+    ChatGPT[ChatGPT] -->|planning and review support| Nick
+    Codex[Codex CLI on Atlas] -->|implements approved changes| Repo
+    Git <--> Repo[Infrastructure repository<br>/srv/repos/AI-Development-Server]
+
+    subgraph Atlas[atlas<br>Ubuntu 26.04 LTS<br>192.168.10.10]
+        Repo
+        Source[Application source repositories<br>/srv/repos]
+        Install[Future install automation<br>install/]
+        Config[Future config templates<br>config/ and templates/]
+        Scripts[Future operational scripts<br>scripts/]
+        Tests[Future smoke tests<br>tests/]
+        SQL[(SQL data volume<br>/sql)]
+        Deploy[Future deployed applications]
+        Nginx[Future nginx reverse proxy]
+        Docker[Future Docker runtime]
+    end
+
+    Repo --> Install
+    Repo --> Config
+    Repo --> Scripts
+    Repo --> Tests
+    Source --> Deploy
+    Deploy --> SQL
+    Nginx --> Deploy
+    Docker --> Deploy
+```
+
+## Decisions Not Yet Made
+
+- Backup destination, schedule, retention, encryption, and restore testing.
+- SQL Server version, installation method, and data layout.
+- nginx site layout, TLS model, and exposure policy.
+- Docker installation method and runtime policy.
+- PlotDirector topology, service names, ports, paths, and rollback process.
+- Monitoring stack and alerting channels.
+- Branching and release policy.
+- CI model.
+- Firewall policy.
+- Production access model.

docs/BUILD-LOG.md

@@ -0,0 +1,102 @@
+# Build Log
+
+This file records chronological Atlas build and infrastructure milestones. Do not fabricate dates, command output, validation results, or operator names.
+
+## Entries
+
+### Date
+
+Not recorded.
+
+### Phase
+
+Baseline server preparation before Phase 1 repository completion.
+
+### Objective
+
+Prepare Atlas as a dedicated AI development server with storage, network, SSH, Git, Gitea access, Codex CLI, and standard development utilities.
+
+### Changes
+
+- Ubuntu 26.04 LTS installed.
+- Hostname set to `atlas`.
+- Static IP configured as `192.168.10.10`.
+- OS SSD configured with full-disk LVM.
+- OS logical volume expanded to use available LVM capacity.
+- SQL SSD mounted at `/sql`.
+- Development SSD mounted at `/srv`.
+- SSH access configured.
+- Gitea SSH authentication configured.
+- Git installed.
+- Git LFS installed.
+- Node.js installed.
+- Standard development utilities installed.
+- Codex CLI installed and authenticated.
+- Codex full-access mode configured with no approval prompts.
+- Passwordless sudo configured for the dedicated development user.
+- Infrastructure repository created and cloned at `/srv/repos/AI-Development-Server`.
+
+### Validation
+
+- Server identity and storage were later inspected during Phase 1 planning.
+- Repository remote was later inspected during Phase 1 planning.
+- Original command output was not captured in this repository.
+
+### Problems
+
+- No baseline problems were recorded in this repository.
+
+### Decisions
+
+- Atlas will use this repository as the authoritative infrastructure and operations source.
+- Atlas will be rebuilt over time through documented, version-controlled, idempotent automation.
+
+### Git Commit
+
+Not yet committed.
+
+### Operator
+
+TODO: Confirm during the relevant implementation phase.
+
+## Entry Template
+
+Copy this template for future entries.
+
+```markdown
+### Date
+
+YYYY-MM-DD
+
+### Phase
+
+Phase name or number.
+
+### Objective
+
+What this work was intended to achieve.
+
+### Changes
+
+- Change made.
+
+### Validation
+
+- Validation performed.
+
+### Problems
+
+- Problem encountered, or `None recorded.`
+
+### Decisions
+
+- Decision made, or `None recorded.`
+
+### Git Commit
+
+Commit hash, or `Not yet committed.`
+
+### Operator
+
+Name or role.
+```

docs/DISASTER-RECOVERY.md

@@ -0,0 +1,283 @@
+# Disaster Recovery
+
+This document defines expected recovery scenarios for Atlas. It does not claim that backups currently exist unless they have been verified.
+
+Backup destination, retention, encryption, restore testing, and ownership are `TODO: Confirm during the relevant implementation phase.`
+
+## Recovery Principles
+
+- Protect source repositories and infrastructure history first.
+- Keep secrets outside this repository.
+- Prefer rebuild from documented automation over manual reconstruction.
+- Validate restored services before returning them to use.
+- Record recovery actions in [BUILD-LOG.md](BUILD-LOG.md).
+
+## OS Disk Failure
+
+### Impact
+
+- Ubuntu installation unavailable.
+- System packages and live configuration on the OS disk unavailable.
+- `/sql` and `/srv` may remain intact if their disks are healthy.
+
+### Required Backups
+
+- Ubuntu installation media.
+- Repository access through Gitea or another verified copy.
+- Copies of live system configuration not yet generated from this repository.
+- Secrets and SSH keys from an approved location outside this repository.
+
+### Recovery Outline
+
+1. Replace the OS disk if required.
+2. Reinstall Ubuntu 26.04 LTS.
+3. Restore hostname, network, SSH, and sudo access.
+4. Remount `/sql` and `/srv`.
+5. Clone or use the existing infrastructure repository.
+6. Run future installation automation when available.
+7. Restore live configuration and services.
+
+### Validation
+
+- Hostname is `atlas`.
+- Static IP address is `192.168.10.10`.
+- `/sql` and `/srv` are mounted.
+- Git can reach Gitea.
+- Required services start and pass smoke tests.
+
+### Remaining Gaps
+
+- OS rebuild automation is not yet implemented.
+- Live configuration inventory is not yet complete.
+
+## SQL Disk Failure
+
+### Impact
+
+- SQL data on `/sql` may be unavailable or lost.
+- Applications depending on SQL Server may be unavailable.
+
+### Required Backups
+
+- Verified SQL backups from outside this repository.
+- SQL Server installation and configuration documentation.
+- SQL credentials from approved secret storage.
+
+### Recovery Outline
+
+1. Replace or repair the SQL disk.
+2. Recreate filesystem and mount at `/sql`.
+3. Reinstall or validate SQL Server.
+4. Restore databases from verified backups.
+5. Reapply permissions and maintenance jobs.
+
+### Validation
+
+- `/sql` is mounted.
+- SQL Server starts.
+- Databases are online.
+- Application connectivity succeeds.
+- Restore validation queries pass.
+
+### Remaining Gaps
+
+- SQL Server is not yet documented as installed by this repository.
+- Backup location, retention, and restore procedure are not yet confirmed.
+
+## Development Disk Failure
+
+### Impact
+
+- `/srv` may be unavailable or lost.
+- Local repository working copies, scripts in progress, build artefacts, and deployment material on `/srv` may be lost.
+
+### Required Backups
+
+- Gitea remote repositories.
+- Any non-committed work that was backed up outside `/srv`.
+- Deployment artefacts only if they cannot be rebuilt from source.
+
+### Recovery Outline
+
+1. Replace or repair the development disk.
+2. Recreate filesystem and mount at `/srv`.
+3. Recreate `/srv/repos`.
+4. Clone required repositories from Gitea.
+5. Recreate build and deployment directories from documented automation.
+
+### Validation
+
+- `/srv` is mounted.
+- `/srv/repos` exists.
+- Infrastructure repository is cloned.
+- Required application repositories are cloned.
+- Smoke tests pass where available.
+
+### Remaining Gaps
+
+- Application repository inventory is not yet documented.
+- Build artefact and deployment location policy is not yet confirmed.
+
+## Complete Server Loss
+
+### Impact
+
+- All local OS, SQL, development, configuration, and service state may be lost.
+- Recovery depends on external repositories, backups, installation media, and secret storage.
+
+### Required Backups
+
+- Gitea-hosted repositories or another off-server Git copy.
+- SQL backups.
+- Secret material from approved secret storage.
+- Configuration not yet represented in this repository.
+- Documentation needed to rebuild storage, network, and services.
+
+### Recovery Outline
+
+1. Replace or rebuild hardware.
+2. Install Ubuntu 26.04 LTS.
+3. Recreate storage layout with `/sql` and `/srv`.
+4. Restore network identity.
+5. Restore SSH and Gitea access.
+6. Clone this repository.
+7. Follow [REBUILD-GUIDE.md](REBUILD-GUIDE.md).
+8. Restore databases and services from verified backups.
+
+### Validation
+
+- Server identity matches documented values.
+- Repositories are restored.
+- Required services pass validation.
+- Applications pass smoke tests.
+- Data restore is verified.
+
+### Remaining Gaps
+
+- Full rebuild is not yet automated.
+- Off-server backup coverage has not been verified in this repository.
+
+## Accidental Repository Deletion
+
+### Impact
+
+- Local infrastructure working copy under `/srv/repos/AI-Development-Server` is lost.
+- Uncommitted changes may be lost.
+
+### Required Backups
+
+- Gitea remote repository.
+- Any external backup containing uncommitted work, if available.
+
+### Recovery Outline
+
+1. Recreate `/srv/repos` if needed.
+2. Clone the repository from Gitea.
+3. Confirm branch and remote.
+4. Reapply any known uncommitted work only from trusted sources.
+
+### Validation
+
+- `git remote -v` shows the expected Gitea remote.
+- `git status` is clean or only shows expected work.
+- Required documentation and scripts are present.
+
+### Remaining Gaps
+
+- Uncommitted work recovery depends on external backups or manual reconstruction.
+
+## Failed Application Deployment
+
+### Impact
+
+- A deployed application may be unavailable, partially updated, or running an unintended version.
+- Source repositories and this infrastructure repository should remain intact.
+
+### Required Backups
+
+- Previous known-good deployment artefact or source revision.
+- Database backup if the deployment includes schema or data changes.
+- Previous live configuration if changed.
+
+### Recovery Outline
+
+1. Stop or isolate the failed deployment if required.
+2. Restore the previous artefact or redeploy the previous source revision.
+3. Restore database state if required and approved.
+4. Restore previous configuration if changed.
+5. Validate application behaviour.
+
+### Validation
+
+- Service status is healthy.
+- nginx routing works if applicable.
+- Application smoke tests pass.
+- Logs show no repeated startup or request failures.
+
+### Remaining Gaps
+
+- Deployment paths, rollback scripts, and smoke tests are not yet defined.
+
+## Configuration Corruption
+
+### Impact
+
+- Services may fail to start or may run with unintended settings.
+- Secret-bearing live configuration may need manual restoration.
+
+### Required Backups
+
+- Repository-managed templates.
+- Backup of live configuration files.
+- Secret values from approved secret storage.
+
+### Recovery Outline
+
+1. Identify the corrupted configuration.
+2. Compare live configuration with repository templates.
+3. Restore from a known-good backup or regenerate from templates.
+4. Reinsert secrets from approved storage without committing them.
+5. Validate and reload affected services.
+
+### Validation
+
+- Service configuration validation passes.
+- Service reload or restart succeeds.
+- Logs show expected behaviour.
+- Application smoke tests pass where available.
+
+### Remaining Gaps
+
+- Live configuration inventory and backup process are not yet complete.
+
+## Credential Compromise
+
+### Impact
+
+- Unauthorised access may be possible to Atlas, Gitea, databases, deployments, external APIs, or backups.
+- Affected credentials must be rotated.
+
+### Required Backups
+
+- Not primarily a backup-driven recovery scenario.
+- Requires access to credential authorities and secret storage.
+
+### Recovery Outline
+
+1. Identify affected credentials and access scope.
+2. Revoke or rotate compromised credentials.
+3. Review logs for misuse.
+4. Update live systems with new credentials.
+5. Confirm no secret values were committed to Git.
+6. If a secret was committed, treat Git history and all clones as compromised for that secret.
+
+### Validation
+
+- Old credentials no longer work.
+- New credentials work only where intended.
+- Services using rotated credentials pass validation.
+- Repository search finds no committed live secret values.
+
+### Remaining Gaps
+
+- Credential inventory, rotation schedule, and incident process are not yet confirmed.

docs/OPERATING-MODEL.md

@@ -0,0 +1,140 @@
+# Operating Model
+
+This document defines how Nick, ChatGPT, and Codex work together on Atlas.
+
+## Roles
+
+- Nick owns architecture approval, operational judgement, production access decisions, and commit approval.
+- ChatGPT supports planning, review, documentation, and implementation guidance.
+- Codex runs on Atlas to inspect the repository, make approved changes, run validation, and report diffs.
+
+## Git as Source of Truth
+
+Git is the source of truth for repository-managed infrastructure and operational intent.
+
+- Infrastructure documentation belongs in this repository.
+- Installation scripts must be version-controlled.
+- Configuration templates must be version-controlled.
+- Manual changes should be recorded and converted to automation where practical.
+- Live secrets and generated artefacts must not be committed.
+
+## Documentation-First Changes
+
+Substantial changes should begin with documentation:
+
+1. Define the problem or objective.
+2. Record relevant assumptions and unknowns.
+3. Update standards, architecture, runbooks, or ADRs as needed.
+4. Implement scripts or templates.
+5. Validate the result.
+6. Review the diff before commit.
+
+## Codex Planning Before Implementation
+
+Codex must inspect the repository and produce a plan before making architecture-level or broad repository changes.
+
+Implementation should start only after Nick approves the plan, unless the request is a narrow mechanical change that clearly does not affect architecture or operations.
+
+## Human Approval of Architecture
+
+Architecture decisions require human approval. Use ADRs for decisions that affect:
+
+- Infrastructure management approach.
+- Service topology.
+- Storage layout.
+- Deployment model.
+- Backup and recovery model.
+- Security boundaries.
+- Tooling choices with long-term maintenance impact.
+
+## Commit Control
+
+Codex must not commit unless explicitly instructed.
+
+Before commit:
+
+- Review `git status`.
+- Review the full relevant diff.
+- Run validation appropriate to the change.
+- Confirm no secrets are present.
+- Ensure documentation and implementation agree.
+
+## Branching Expectations
+
+Default branch:
+
+- `main`
+
+Branching model:
+
+- `TODO: Confirm during the relevant implementation phase.`
+
+Until a fuller branching model exists, keep work small, reviewable, and easy to revert.
+
+## Diff Review
+
+Every change should be reviewed with `git diff` before commit.
+
+Review should check:
+
+- Behavioural intent.
+- File paths.
+- Secrets exposure.
+- Inconsistent terminology.
+- Broken Markdown links.
+- Missing validation.
+- Unintended generated files.
+
+## Testing Before Commit
+
+Run the strongest practical validation before commit.
+
+For documentation-only changes, validation should include:
+
+- Repository tree inspection.
+- Markdown link checks where practical.
+- Search for accidental secrets.
+- Search for inconsistent server names, IP addresses, and mount paths.
+- `git diff --check`.
+
+For scripts and service changes, validation should also include syntax checks, dry runs where available, and smoke tests.
+
+## Rollback Expectations
+
+- Prefer changes that can be reversed through Git and idempotent scripts.
+- Document rollback steps for service-affecting changes.
+- Preserve previous configuration where practical before replacing live files.
+- Remember that Git rollback does not automatically undo external system state.
+
+## Handling of Secrets
+
+- Do not commit secrets.
+- Do not print secrets in logs or command output.
+- Do not copy Codex authentication material into the repository.
+- Use templates, examples, and documented environment variable names.
+- Store live secrets outside this repository.
+- Rotate credentials after suspected exposure.
+
+Secret storage mechanism is `TODO: Confirm during the relevant implementation phase.`
+
+## Handling of Production Access
+
+Production access must be deliberate and documented.
+
+- Do not assume development and production permissions are the same.
+- Do not embed production credentials in scripts.
+- Do not run production-impacting commands without explicit approval.
+- Record deployment and rollback expectations before automating production changes.
+
+Production access model is `TODO: Confirm during the relevant implementation phase.`
+
+## Development and Production Responsibilities
+
+Atlas is currently documented as a development server. Future production responsibilities must be explicitly approved before they are added.
+
+Expected separation:
+
+- Development: source work, automation development, local validation, builds, and staging-like testing.
+- Production: live application availability, production data protection, externally exposed endpoints, customer-impacting deployments, and incident response.
+
+Whether Atlas will host production workloads is `TODO: Confirm during the relevant implementation phase.`

docs/REBUILD-GUIDE.md

@@ -0,0 +1,165 @@
+# Rebuild Guide
+
+This guide describes the planned rebuild path for Atlas. At Phase 1, the repository contains documentation but no executable installation phases. Steps marked as TODO are not yet automated.
+
+## Automation Status
+
+- Repository structure and documentation: present.
+- Installation scripts: not yet created.
+- Configuration templates: not yet created.
+- Operational scripts: not yet created.
+- Smoke tests: not yet created.
+- Backup and restore automation: not yet created.
+
+## Preconditions
+
+- Physical server hardware is available.
+- Ubuntu 26.04 LTS installation media is available.
+- Network details for Atlas are known.
+- Gitea SSH access can be restored or re-created.
+- Required secrets and private keys are available from an approved location outside this repository.
+- Backups are available where required.
+
+Backup inventory and credential recovery process are `TODO: Confirm during the relevant implementation phase.`
+
+## 1. Ubuntu Installation
+
+1. Install Ubuntu 26.04 LTS on the OS SSD.
+2. Set hostname to `atlas`.
+3. Create the dedicated development user.
+4. Configure administrative access for the development user.
+5. Apply operating system updates.
+
+Exact installer choices, partitioning profile, and user creation procedure are `TODO: Confirm during the relevant implementation phase.`
+
+## 2. Storage Preparation
+
+Target storage layout:
+
+- OS volume mounted at `/`
+- SQL data volume mounted at `/sql`
+- Development volume mounted at `/srv`
+- Repository root at `/srv/repos`
+
+Current Phase 1 status:
+
+- `/sql` is the intended SQL data volume.
+- `/srv` is the primary development volume.
+- Idempotent storage preparation scripts do not exist yet.
+
+Future rebuild work must document:
+
+- Disk identification method.
+- Filesystem labels or UUIDs.
+- `/etc/fstab` entries.
+- Mount validation commands.
+- Ownership and permissions.
+
+These details are `TODO: Confirm during the relevant implementation phase.`
+
+## 3. Network Setup
+
+Target identity:
+
+- Hostname: `atlas`
+- Static IP address: `192.168.10.10`
+- Default gateway: `192.168.10.1`
+- Primary interface: `enp3s0`
+
+Configure DNS, host mappings, firewall rules, and public exposure only after the relevant policy is confirmed.
+
+DNS and firewall details are `TODO: Confirm during the relevant implementation phase.`
+
+## 4. SSH
+
+1. Install or enable OpenSSH.
+2. Confirm SSH access from trusted administration clients.
+3. Restore or create the SSH key needed for Gitea access.
+4. Keep private keys outside this repository.
+
+SSH hardening policy, trusted client list, and key rotation procedure are `TODO: Confirm during the relevant implementation phase.`
+
+## 5. Repository Checkout
+
+Create the repository root if needed:
+
+```bash
+sudo mkdir -p /srv/repos
+```
+
+Clone the infrastructure repository:
+
+```bash
+cd /srv/repos
+git clone git@git.catherinelynwood.com:atlas-bot/AI-Development-Server.git
+cd AI-Development-Server
+```
+
+If the remote repository is unavailable, follow the disaster recovery guidance in [DISASTER-RECOVERY.md](DISASTER-RECOVERY.md).
+
+## 6. Bootstrap Process
+
+At Phase 1, bootstrap is manual. Future bootstrap should be reduced to a documented command sequence that runs idempotent scripts from this repository.
+
+Planned bootstrap flow:
+
+1. Review [README.md](../README.md).
+2. Review [SERVER-STANDARDS.md](../SERVER-STANDARDS.md).
+3. Review this rebuild guide.
+4. Run base installation validation.
+5. Run ordered installation scripts from `install/` when they exist.
+6. Run smoke tests from `tests/` when they exist.
+
+Bootstrap command sequence is `TODO: Confirm during the relevant implementation phase.`
+
+## 7. Running Installation Phases
+
+Planned scripts may include:
+
+```text
+install/01-base-tools.sh
+install/02-dotnet.sh
+install/03-sqlserver.sh
+install/04-nginx.sh
+install/05-docker.sh
+```
+
+These scripts do not exist yet. When created, each script must:
+
+- Be idempotent.
+- Validate prerequisites.
+- Log concise progress.
+- Avoid printing secrets.
+- Document rollback expectations.
+- Include or reference validation steps.
+
+## 8. Validation
+
+Minimum rebuild validation should confirm:
+
+- Hostname is `atlas`.
+- Static IP address is `192.168.10.10`.
+- `/sql` is mounted.
+- `/srv` is mounted.
+- `/srv/repos` exists.
+- Git can reach Gitea over SSH.
+- This repository is checked out.
+- Required installation phases have run successfully.
+- Smoke tests pass.
+
+Validation scripts are `TODO: Confirm during the relevant implementation phase.`
+
+## 9. Restoring Services and Data
+
+Restoration order should be:
+
+1. Restore base OS access.
+2. Restore storage mounts.
+3. Restore repository access.
+4. Run installation automation.
+5. Restore configuration generated from templates.
+6. Restore SQL data from verified backups.
+7. Restore deployed applications or rebuild them from source.
+8. Validate services and application behaviour.
+
+SQL backup location, deployment artefact policy, restore commands, and service validation are `TODO: Confirm during the relevant implementation phase.`

docs/adr/0001-infrastructure-as-code.md

@@ -0,0 +1,33 @@
+# 0001: Infrastructure as Code
+
+## Status
+
+Accepted
+
+## Context
+
+Atlas is a dedicated AI development server intended to be rebuildable from a clean Ubuntu installation. The server needs a practical source of truth for architecture, standards, installation automation, configuration templates, operational scripts, tests, recovery procedures, architectural decisions, and build history.
+
+Manual server changes are difficult to audit and repeat. A repository-managed approach gives Atlas a reviewable history and creates a path toward reliable rebuilds.
+
+## Decision
+
+Atlas will be managed using Infrastructure as Code principles.
+
+This repository is the authoritative source for Atlas infrastructure and operations. Installation and operational automation will be implemented as documented, version-controlled, idempotent scripts. Configuration will be represented through repository-managed templates where practical. Unknown details will remain documented as TODOs until the relevant implementation phase confirms them.
+
+## Consequences
+
+- Infrastructure changes must be reviewable in Git.
+- Manual changes should be documented and converted into automation where practical.
+- Scripts must be safe to rerun.
+- Documentation is part of the operational system and must be maintained.
+- Secrets must remain outside the repository.
+- Rebuild and recovery should become more reliable as automation is added.
+- Initial progress may be slower because standards and documentation are created before automation.
+
+## Alternatives considered
+
+- Continue managing the server manually. This was rejected because it would make rebuilds, audits, and recovery harder.
+- Use ad hoc scripts outside Git. This was rejected because it would not provide reliable history or review.
+- Adopt a heavier configuration-management system immediately. This was deferred because Atlas is currently a single server and Bash scripts are sufficient for the initial phase.

docs/adr/README.md

@@ -0,0 +1,40 @@
+# Architecture Decision Records
+
+Architecture Decision Records capture decisions that affect the long-term structure, operation, security, or rebuildability of Atlas.
+
+## When to Create an ADR
+
+Create an ADR for decisions about:
+
+- Infrastructure management approach.
+- Service topology.
+- Storage layout.
+- Deployment model.
+- Backup and recovery model.
+- Security and trust boundaries.
+- Tooling choices with long-term maintenance impact.
+
+Small implementation details do not need ADRs unless they establish a precedent.
+
+## Naming Convention
+
+Use a four-digit sequence number and a short lower-case slug:
+
+```text
+0001-infrastructure-as-code.md
+0002-example-decision.md
+```
+
+Do not renumber existing ADRs.
+
+## Required Sections
+
+Each ADR should include:
+
+- Status
+- Context
+- Decision
+- Consequences
+- Alternatives considered
+
+Accepted ADRs remain part of the historical record. If a decision changes, create a new ADR that supersedes the earlier one.

install/README.md

@@ -0,0 +1,48 @@
+# Install
+
+This directory is reserved for ordered, idempotent installation scripts for Atlas.
+
+## What Belongs Here
+
+- Bootstrap scripts.
+- Package installation scripts.
+- Service installation scripts.
+- Storage, runtime, and tooling setup scripts.
+- Validation wrappers for installation phases.
+
+## What Must Not Be Stored Here
+
+- Secrets, passwords, tokens, private keys, or live credentials.
+- One-off experiments.
+- Generated logs.
+- Downloaded package caches.
+- Application source code.
+- Deployment artefacts.
+
+## Naming Conventions
+
+Use a two-digit numeric prefix followed by a short lower-case hyphenated name:
+
+```text
+01-base-tools.sh
+02-dotnet.sh
+03-sqlserver.sh
+04-nginx.sh
+05-docker.sh
+```
+
+Scripts must follow [SERVER-STANDARDS.md](../SERVER-STANDARDS.md).
+
+## Expected Future Structure
+
+Phase scripts may be added directly under this directory at first. If the directory grows, shared helpers may be added under a clearly named subdirectory.
+
+Future structure is `TODO: Confirm during the relevant implementation phase.`
+
+## Security Considerations
+
+- Use `sudo` only for commands that need it.
+- Do not print secrets.
+- Do not embed credentials.
+- Validate package sources and signing keys.
+- Make scripts safe to rerun.

scripts/README.md

@@ -0,0 +1,49 @@
+# Scripts
+
+This directory is for operational scripts used after Atlas is installed.
+
+## What Belongs Here
+
+- Backup scripts.
+- Restore scripts.
+- Deployment scripts.
+- Maintenance scripts.
+- Monitoring scripts.
+- Service validation helpers.
+
+## What Must Not Be Stored Here
+
+- Installation phase scripts. Those belong in `install/`.
+- Secrets or credentials.
+- Generated logs.
+- Temporary files.
+- Build artefacts.
+- One-off experimental commands.
+
+## Naming Conventions
+
+- Use lower-case hyphenated names.
+- Prefer verb-target names, such as `backup-sql.sh` or `check-disk-space.sh`.
+- Group scripts by operational area when useful.
+- Executable permissions should be used only for scripts intended to run directly.
+
+## Expected Future Structure
+
+Current planned areas include:
+
+```text
+scripts/backup/
+scripts/deploy/
+scripts/maintenance/
+scripts/monitoring/
+scripts/restore/
+```
+
+Additional areas may be added when a repeated operational need exists.
+
+## Security Considerations
+
+- Do not print secrets.
+- Do not store credentials in scripts.
+- Make destructive actions explicit and documented.
+- Include validation and rollback guidance for service-affecting scripts.

scripts/backup/.gitkeep

@@ -0,0 +1 @@
+

scripts/deploy/.gitkeep

@@ -0,0 +1 @@
+

scripts/maintenance/.gitkeep

@@ -0,0 +1 @@
+

scripts/monitoring/.gitkeep

@@ -0,0 +1 @@
+

scripts/restore/.gitkeep

@@ -0,0 +1 @@
+

templates/README.md

@@ -0,0 +1,36 @@
+# Templates
+
+This directory is for reusable templates that do not belong to one specific service directory under `config/`.
+
+## What Belongs Here
+
+- Generic environment file examples.
+- Reusable script templates.
+- Documentation templates.
+- Deployment manifest examples.
+- Non-secret placeholder files.
+
+## What Must Not Be Stored Here
+
+- Live `.env` files.
+- Passwords, tokens, private keys, or certificates.
+- Generated credentials.
+- Live service configuration.
+- Build artefacts.
+- Backups.
+
+## Naming Conventions
+
+- Use lower-case hyphenated names.
+- Use `.template`, `.example`, or `.sample` suffixes where appropriate.
+- Use obvious placeholder values such as `CHANGE_ME` or `${ENV_VAR_NAME}`.
+
+## Expected Future Structure
+
+Subdirectories may be introduced when templates grow beyond a small number of files.
+
+Future structure is `TODO: Confirm during the relevant implementation phase.`
+
+## Security Considerations
+
+Templates are version-controlled and must be safe to publish to anyone with repository access. Never include a live credential, even temporarily.

tests/README.md

@@ -0,0 +1,39 @@
+# Tests
+
+This directory is for smoke tests and validation checks for Atlas infrastructure.
+
+## What Belongs Here
+
+- Smoke tests for installation phases.
+- Validation checks for mounts, services, network identity, and repository state.
+- Script syntax checks.
+- Non-secret test fixtures.
+
+## What Must Not Be Stored Here
+
+- Secrets.
+- Real production data.
+- SQL backups.
+- Large generated test output.
+- Package caches.
+- Environment-specific local overrides.
+
+## Naming Conventions
+
+- Use lower-case hyphenated names.
+- Prefer names that describe the observable behaviour being checked.
+- Group tests by area when useful, for example `tests/smoke/`.
+
+## Expected Future Structure
+
+Current planned areas include:
+
+```text
+tests/smoke/
+```
+
+Additional test groups should be added only when they have clear ownership and purpose.
+
+## Security Considerations
+
+Tests must not expose secrets or mutate production data unless explicitly designed and approved. Prefer read-only validation where practical.

tests/smoke/.gitkeep

@@ -0,0 +1 @@
+