Docker Image and first iteration

AGENTS.md

@@ -0,0 +1,94 @@
+# AGENTS.md
+
+## Project Overview
+
+This repository is a foundational Dockerized Django portfolio website. Local
+development currently uses SQLite and a single Docker Compose `web` service.
+Do not assume a frontend stack, deployment platform, or CI provider unless the
+repository explicitly defines one.
+
+## Working Principles
+
+- Prefer small, reviewable changes with a clear purpose.
+- Inspect the repository before making changes. Follow existing patterns once
+  they exist instead of introducing parallel conventions.
+- Keep local development Docker-first. Add and document Docker Compose commands
+  when the Compose configuration is introduced.
+- Do not hard-code credentials, secret keys, hostnames, or environment-specific
+  configuration.
+- Update `README.md`, this file, and `SECURITY.md` when implementation changes
+  make their instructions inaccurate.
+
+## Django Conventions
+
+- Keep environment-specific settings outside committed source code. Load
+  sensitive values from environment variables or a deployment secret store.
+- Organize Django apps by domain responsibility. Avoid creating apps solely to
+  mirror technical layers.
+- Use Django migrations for schema changes. Commit generated migration files
+  with the code that requires them.
+- Review migrations before committing them. Avoid destructive schema changes
+  without an explicit data migration or rollout plan.
+- Keep views, forms, serializers, templates, and models focused. Extract shared
+  behavior only when there is a concrete reuse case.
+- Use Django's built-in security protections unless there is a documented
+  reason to override them.
+
+## Docker Workflow
+
+Docker Compose is the preferred local interface:
+
+```sh
+docker compose up --build -d
+docker compose exec web python manage.py check
+docker compose exec web python manage.py migrate
+docker compose exec web python manage.py test
+docker compose run --rm frontend npm run test
+docker compose run --rm frontend npm run build
+docker compose down
+```
+
+Keep containers reproducible:
+
+- Pin runtime versions and dependency versions using the chosen package
+  manager's lock mechanism.
+- Run application processes as a non-root user where practical.
+- Do not bake secrets or local environment files into images.
+- Add a `.dockerignore` when Docker files are introduced.
+- Use a `.env.example` to record environment variables, and do not touch the production `.env`.
+- The Web Container should be entirely self contained, without splitting the functionality into multiple containers. It should include both backend, frontend, integrated database, webserver, etc.
+
+## Frontend Conventions
+
+- Keep Django responsible for page rendering and use React only for focused
+  interactive islands unless the architecture is intentionally changed.
+- Build frontend assets with the one-shot Docker Compose `frontend` service.
+- Keep npm dependencies pinned and commit `frontend/package-lock.json`.
+- Keep generated frontend bundles out of version control. The Docker image
+  builds its own production bundle.
+- Treat committed TopoJSON map files as generated assets derived from Natural
+  Earth data. Regenerate them deliberately rather than editing them by hand.
+
+## Validation
+
+Before considering a change complete, run the checks supported by the current
+repository. Once available, this should include:
+
+- Django system checks.
+- The automated test suite.
+- Migration consistency checks.
+- Formatting, linting, and type checks selected by the project.
+- A Docker image build and a basic container startup check for infrastructure
+  changes.
+
+If a check is not yet configured or cannot be run, state that clearly in the
+change summary. Do not invent placeholder commands that appear executable.
+
+## Change Hygiene
+
+- Never commit `.env` files, secret values, local databases, uploaded media,
+  caches, or generated build output.
+- Add tests for behavior changes and regression fixes once the test harness
+  exists.
+- Keep documentation aligned with actual repository behavior.
+- Avoid unrelated refactors in focused feature or bug-fix changes.