diff --git a/Makefile b/Makefile
index 586ee98..ccd433d 100644
--- a/Makefile
+++ b/Makefile
@@ -1,53 +1,26 @@
 NAME := goose
 PKG_NAME := $(NAME)
 TOOL2RPM := rust2rpm
-FAS_USERNAME := r0x0d
-FILES_TO_SYNC := $(wildcard *.src.rpm) $(wildcard *.spec) generate-vendor-tarball.sh
-
-ifneq ("$(wildcard rust2rpm.toml)","")
-FILES_TO_SYNC += rust2rpm.toml
-endif
+FAS_USERNAME := $(shell copr whoami)
 
 .PHONY: create-copr-repo
 create-copr-repo:
 	copr create \
-		--chroot fedora-43-x86_64 \
-		--chroot fedora-44-x86_64 \
 		--chroot fedora-rawhide-x86_64 \
 		$(NAME)
 
-.PHONY: create-gh-repo
-create-gh-repo:
-	git init
-	git add . && git commit -m "Initial commit for $(NAME)"
-	gh repo create $(NAME) \
-		--public \
-		--disable-wiki \
-		--remote origin \
-		--source . \
-		--push \
-		--description "Upstream rpm repository for https://github.com/block/goose"
-
-.PHONY: spec
-spec:
-	@echo "Goose is not packaged in crates.io. Skipping."
-
 .PHONY: sources
 sources:
 	spectool -g $(NAME).spec
 
 .PHONY: srpm
 srpm:
-	fedpkg srpm
+	fedpkg --release rawhide srpm
 
 .PHONY: build
-build: srpm
+build: srpm 
 	copr build $(NAME) $(NAME)*.src.rpm \
-		--chroot fedora-43-x86_64 \
-		--chroot fedora-44-x86_64 \
 		--chroot fedora-rawhide-x86_64 \
-		--chroot epel-9-x86_64 \
-		--chroot epel-10-x86_64 \
 		--timeout 36000
 
 .PHONY: logs
@@ -55,9 +28,9 @@ logs:
 	@command -v fuzzytail > /dev/null || { echo >&2 "fuzzytail is not installed. Install with pip install fuzzytail"; }
 	fuzzytail watch $(FAS_USERNAME)/$(NAME)
 
-.PHONY: sync
-sync:
-	scp $(FILES_TO_SYNC) $(FAS_USERNAME)@fedorapeople.org:/home/fedora/$(FAS_USERNAME)/public_html/$(NAME)
+.PHONY: clean
+clean:
+	rm -rf *.src.rpm *.tar.gz *.tar.xz *.crate vendor
 
 .PHONY: freeze
 freeze:
diff --git a/README.md b/README.md
index f622b7c..2e2bdfa 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,22 @@
-[![Copr build status](https://copr.fedorainfracloud.org/coprs/r0x0d/goose/package/goose/status_image/last_build.png)](https://copr.fedorainfracloud.org/coprs/r0x0d/goose/package/goose/)
+[![Copr build status](https://copr.fedorainfracloud.org/coprs/g/rhel-lightspeed/goose/package/goose/status_image/last_build.png)](https://copr.fedorainfracloud.org/coprs/g/rhel-lightspeed/goose/package/goose/)
 
 # goose
 
-* [COPR repo](https://copr.fedorainfracloud.org/coprs/r0x0d/goose)
-* [Upstream repo](https://github.com/block/goose)
-* [Upstream license](https://github.com/block/goose/blob/main/LICENSE)
-* [Fedora Package Review Bugzilla](TODO)
+This is the development repository for the Fedora/RHEL RPM packaging of
+[goose](https://github.com/block/goose). It is the upstream source for the
+dist-git version of the package. Changes are developed and tested here before
+being submitted to dist-git.
+
+* [COPR repo](https://copr.fedorainfracloud.org/coprs/g/rhel-lightspeed/goose)
+* [Upstream repo](https://github.com/aaif-goose/goose)
+* [Upstream license](https://github.com/aaif-goose/goose/blob/main/LICENSE)
+* [Fedora Package Review Bugzilla](https://bugzilla.redhat.com/show_bug.cgi?id=2428704)
+
+## Documentation
+
+- [Makefile Reference](docs/makefile.md) -- build targets and typical workflow
+- [Version Update Process](docs/update-process.md) -- how to update to a new
+  upstream version
 
 ## Setup
 
@@ -29,30 +40,7 @@ To build this RPM via copr, the following commands are required:
 make sources
 
 # Will perform two operations:
-#   * Generate a new srpm with `fedpkg srpm`
+#   * Generate a new srpm with `fedpkg --release rawhide srpm`
 #   * Request a new build on copr
 make build
-```
-
-## Push to Github (optional)
-
-This step is optional, but it will secure that the specfile and other settings
-are persisted somewhere.
-
-```bash
-# Create a new repository in your account using `gh` and some pre-defined
-# settings.
-make create-gh-repo
-```
-
-## Generate patches for downstream
-
-```bash
-git clone git@github.com:block/goose goose-source
-cd goose-source
-git checkout $TAG
-# ... modify the source ...
-git add -u && git commit
-# ... write your commit message ...
-git format-patch -<number of commits to generate patch>
-```
+```
\ No newline at end of file
diff --git a/docs/makefile.md b/docs/makefile.md
new file mode 100644
index 0000000..54bf152
--- /dev/null
+++ b/docs/makefile.md
@@ -0,0 +1,116 @@
+# Makefile Reference
+
+This document describes the Makefile targets available for building and
+managing the goose RPM package.
+
+## Prerequisites
+
+The following tools must be available in your environment, either installed
+locally or inside a development container:
+
+- `fedpkg`
+- `spectool`
+- `copr-cli`
+- `fuzzytail` (optional, for `make logs`)
+
+## Targets
+
+### `create-copr-repo`
+
+Creates a new [COPR](https://copr.fedorainfracloud.org) repository for
+building goose. This is a one-time setup step and only needs to be run when
+bootstrapping the project from scratch.
+
+The repository is created with the following chroots enabled:
+
+- `fedora-rawhide-x86_64`
+
+```bash
+make create-copr-repo
+```
+
+### `sources`
+
+Downloads the source tarballs defined in `goose.spec` using `spectool`. The
+files are placed in the repository root directory.
+
+```bash
+make sources
+```
+
+### `srpm`
+
+Generates a source RPM (`.src.rpm`) using `fedpkg` targeting the Rawhide
+release. This is automatically called by the `build` target, but can be run
+independently to verify that the spec file produces a valid SRPM.
+
+```bash
+make srpm
+```
+
+### `build`
+
+Builds the package in COPR. This target first generates an SRPM (via the
+`srpm` dependency), then submits it to the COPR build system targeting
+`fedora-rawhide-x86_64` with a 10-hour timeout.
+
+```bash
+make build
+```
+
+### `logs`
+
+Watches COPR build logs in real time using
+[fuzzytail](https://pypi.org/project/fuzzytail/). Requires `fuzzytail` to be
+installed (`pip install fuzzytail`). The command will display an error message
+if the tool is not found.
+
+```bash
+make logs
+```
+
+### `clean`
+
+Removes generated build artifacts from the repository root:
+
+- `*.src.rpm` -- source RPMs
+- `*.tar.gz`, `*.tar.xz` -- source tarballs
+- `*.crate` -- Rust crate archives
+- `vendor/` -- vendored dependencies directory
+
+```bash
+make clean
+```
+
+### `freeze`
+
+Freezes Python dependency versions for the goose Python extensions. Runs
+`scripts/freeze.py` targeting Python 3.14 to produce pinned requirement files
+under `requirements/`.
+
+```bash
+make freeze
+```
+
+## Typical Workflow
+
+A standard build cycle looks like this:
+
+```bash
+# 1. Download the sources defined in the spec file
+make sources
+
+# 2. Build the SRPM and submit to COPR
+make build
+
+# 3. (Optional) Watch the build logs
+make logs
+
+# 4. Clean up artifacts when done
+make clean
+```
+
+## Related Documentation
+
+- [Version Update Process](update-process.md) -- how to update goose to a new
+  upstream version using the Claude Code automation