Updated docs.

AGENTS.md

@@ -4,6 +4,14 @@
 
 Cthulhu must never depend on a specific Linux init system or service manager. This applies to the reader, Tentacles, process supervision, installation, packaging, and required tests. Do not require systemd, `systemd-run`, `systemctl`, or a systemd user manager. Use init-independent Linux interfaces and detect the capabilities actually available. Cthulhu and its Tentacles must work on non-systemd distributions, including Artix.
 
+## Before Starting a Fix or Feature
+
+Inspect `git status --short --branch`, confirm the intended branch and upstream, and complete `git pull --ff-only` before starting implementation. If local and upstream commits have diverged, resolve that divergence with a normal merge before proceeding; never discard local work to make the pull succeed. If a merge or rebase is already in progress, finish it first. Preserve uncommitted changes and diagnostic files; do not automatically stash, reset, or clean them.
+
+On every branch other than `testing` or `master`, also fetch the maintained repository's latest `testing` branch and merge it into the working branch. With the maintained repository configured as `origin`, use `git fetch origin` followed by `git merge origin/testing`. Resolve conflicts, run the relevant checks, and finish any merge commit before starting the new work. An unresolved or failed synchronization blocks implementation. Do not merge `testing` into `master` as part of this preparation; release integration is separate.
+
+After synchronization, check whether the reported issue still exists and inspect recent changes before implementing a fix. Another contributor may already have fixed it. See [the contributor synchronization procedure](CONTRIBUTING.md#update-your-branch-before-starting-work), including instructions for a new branch without an upstream.
+
 ## Project Structure & Module Organization
 
 Cthulhu is a Go Linux screen reader. `cmd/` contains executables; `internal/` owns reader subsystems. Embedded audio lives in `assets/sounds/`, Tentacle libraries in `sdk/`, native harnesses in `tests/`, and parity records in `testdata/`. Go tests sit beside implementation files. Arch packaging lives in `distro-packages/Arch-Linux/cthulhu-git/`.

CONTRIBUTING.md

@@ -2,6 +2,27 @@
 
 Read [README.md](README.md) and [AGENTS.md](AGENTS.md) first. Start with a user-visible behavior and reproduce the issue in the current code. The maintained repository is `git.stormux.org/storm/cthulhu`; confirm the intended target branch with the maintainer. The `legacy` branch preserves Python Cthulhu; the current checkout is the Go implementation.
 
+## Update Your Branch Before Starting Work
+
+Update your checkout before starting each fix or feature. This helps avoid fixing an issue that another contributor has already resolved.
+
+1. Run `git status --short --branch` and confirm you are on the intended branch. If a merge or rebase is in progress, finish it first. Preserve any uncommitted work and diagnostic files before updating; do not discard them or automatically stash them.
+2. Run `git pull --ff-only` to update the current branch from its configured upstream. A successful pull saying the branch is already up to date also satisfies this step. If Git reports divergent branches, merge the intended upstream into your branch and resolve the conflicts before continuing. Ask for help if you are unsure; do not use a reset or force push to make the error disappear.
+3. If your branch is neither `testing` nor `master`, also run:
+
+   ```sh
+   git fetch origin
+   git merge origin/testing
+   ```
+
+   These commands bring the latest shared development changes into your contributor branch. They assume `origin` points to the maintained repository. If `origin` is your fork, use the remote for the maintained repository in both commands instead. If you are unsure which remote that is, ask before merging.
+4. Resolve any conflicts, run the relevant checks, and complete any merge commit before starting implementation. A failed pull or an unfinished merge means the update is not complete.
+5. Reproduce the reported issue again and review recent changes. If it is already fixed, verify the existing fix rather than writing a second implementation.
+
+For a new local branch without an upstream, first update `testing` with `git pull --ff-only`, then create your contributor branch from that updated `testing`. Do this before making changes. Existing contributor branches still need the merge from the maintained repository's latest `testing` described above.
+
+Do not merge `testing` into `master` during this preparation. Updating `master` from its own upstream and integrating a release are separate operations. The historical Python `legacy` branch is not a target for Go changes.
+
 ## Proposing a Change
 
 Keep each change to one complete behavior. Describe the reproduction, expected result, affected subsystem, and plausible regressions. A reported application or page is a reproduction case: fix the shared layer when it explains the defect. Use an application-specific script only when a shared fix would be wrong; document and test the exception.