From 4b3e4d1e52d6700818f8ced8dee0fd8c3e23583b Mon Sep 17 00:00:00 2001
From: Mathew Sir Guest the best <mathew@zavage.net>
Date: Sat, 30 May 2026 20:41:26 -0600
Subject: [PATCH] docs: add CLAUDE.md guidance and refresh README

Document the project overview, commands, code style, and architecture
in CLAUDE.md, update the README for the Poetry/Click workflow, and add
local Claude Code permission settings.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md | 11 +++++------
 2 files changed, 62 insertions(+), 6 deletions(-)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..0fe7660
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+SmileyFace is a Python CLI tool for automating Unreal Tournament 4 (UT4) server administration. It handles building local server instances from custom maps/mutators/configs, deploying them to remote game and redirect servers via rsync/SSH, and managing server lifecycle (start/stop/restart).
+
+## Commands
+
+```bash
+# Install dependencies
+poetry install
+
+# Run the tool
+python smileyface.py --help
+
+# Format code
+black smileyface/
+isort --profile black --filter-files smileyface/
+
+# Lint
+flake8 smileyface/
+
+# Run pre-commit hooks manually
+pre-commit run --all-files
+```
+
+There is no test suite.
+
+## Code Style
+
+- **Black** formatter: 120 char line length, target Python 3.13
+- **isort**: profile black, multi_line_output=3, trailing commas, force_grid_wrap=3
+- **flake8**: 120 char max, ignores E121/E123/E126/E226/E24/E704/W605
+
+## Architecture
+
+The app uses **Click** for CLI dispatch, **pydantic-settings** for configuration, and stdlib `logging` for log management.
+
+**Entry point**: `smileyface.py` (project root) imports `smileyface.start_app()` which invokes the Click CLI.
+
+**Configuration**: `AppSettings` (`settings.py`) is a pydantic `BaseSettings` model. Config is loaded from environment variables (prefix `SMILEYFACE_`) or a `.env` file. See `.env.example` for all available settings.
+
+**Context**: `AppContext` (`context.py`) holds the `settings` instance and a dict-like `log` accessor. Passed to all command classes as `ctx`.
+
+**CLI**: `cli.py` defines Click commands that instantiate the context and delegate to class methods.
+
+**Key classes**:
+- `UT4ServerMachine` (`hub_machine.py`) - Core logic. Each CLI subcommand (generate_instance, upload_server, upload_redirects, etc.) is a method here. This is the largest and most important file.
+- `DataLayer` (`datalayer/datalayer.py`) - Lazy SQLite3 connection wrapper.
+- `DbFuncs` (`datalayer/db_ops.py`) - Database operations for tracking pak file state (MD5 sums, validation).
+- `GameIniSpecial` (`gameconfig_edit.py`) - Generates redirect references in Game.ini for custom pak files.
+
+**Deployment flow**: `oneclickdeploy` chains `generate_instance` -> `upload_redirects` -> `upload_server`. The generate step builds a local instance directory with the server binary, configs, maps, and mutators. Upload steps rsync to remote hosts.
+
+**Scraping module** (`scrape_latest/`) uses Selenium to scrape pak file listings from ut4pugs.us and utcc.unrealpugs.com for MD5 validation against local files.
diff --git a/README.md b/README.md
index 28ce41d..290313e 100644
--- a/README.md
+++ b/README.md
@@ -3,18 +3,17 @@
 See official website, [https://zavage-software.com/portfolio/smileyface](https://zavage-software.com/portfolio/smileyface) for instructions.
 
 # Dependencies
- * [app_skellington](https;//zavage-software.com/projects/app_skellington)
-  * [appdirs](https://pypi.org/project/appdirs)
-  * [colorlog](https://pypi.org/project/colorlog)
-  * [configobj](https://pypi.org/project/configob)
+ * [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)
+ * [click](https://click.palletsprojects.com)
+ * [platformdirs](https://pypi.org/project/platformdirs)
  * [selenium](https://selenium-python.readthedocs.io)
  * [sqlparse](https://pypi.org/project/sqlparse)
 
 Installation
 ============
-Activate your desired python environment or install system-wide with admin privileges.
+Activate your desired python environment, then:
 
-    python setup.py install
+    poetry install
 
 Usage
 ======