Docs(refactor[agents]): Route instead of restate

why: AGENTS.md is read on every task, so a policy that matters to one
class of change costs context on all the others. Splitting how we work
from how we write lets each be loaded when it applies, and keeps both
discoverable to humans rather than only to agents.

what:
- Replace the AGENTS.md body with a router: the project map, universal
  change discipline, then one pointer per class of change
- Add .github/WRITING.md for prose policy, including the CLI's real
  exit-status/stdout/stderr contract, the logging key schema, and the
  Django-shape CHANGES conventions
- Add .github/CONTRIBUTING.md for workflow policy, with real gate
  commands read from pyproject.toml, the Makefile, and CI
- Rename .github/contributing.md to .github/CONTRIBUTING.md, keeping
  its Decorum section
- Delete docs/AGENTS.md and docs/CLAUDE.md, now absorbed into
  .github/WRITING.md
- Turn docs/project/contributing.md and docs/project/code-style.md
  into pointer pages at the canonical files, since a Sphinx {include}
  of a file outside docs/ rewrites its links into dead anchors
- Correct README's Python version claim and the developmental-release
  uv commands, which were missing --prerelease and could not work

Author: tony

.github/CONTRIBUTING.md

@@ -0,0 +1,167 @@
+# Contributing
+
+Thanks for looking. A bug report with a reproduction — the directory layout
+and the exact `g` invocation — is the most useful thing you can send; a
+correction to somewhere the documentation misled you is a close second.
+
+How this project writes prose — README, `CHANGES`, commit messages,
+docstrings, source comments, and CLI/error text — is set out separately in
+[WRITING.md](WRITING.md). Read that before changing any of it. The
+constraints every change is held to, and the map of what is where, are in
+[AGENTS.md](../AGENTS.md).
+
+## Getting set up
+
+Install [uv], then sync the dev and docs extras:
+
+```console
+$ uv sync --all-extras --dev
+```
+
+[uv]: https://github.com/astral-sh/uv
+
+## The gates
+
+CI is the order of record; every gate it runs has to pass before a change is
+done.
+
+Format:
+
+```console
+$ uv run ruff format .
+```
+
+Lint:
+
+```console
+$ uv run ruff check . --fix --show-fixes
+```
+
+Type-check (`[tool.mypy] strict = true`):
+
+```console
+$ uv run mypy .
+```
+
+Test:
+
+```console
+$ uv run py.test
+```
+
+Documentation is a gate, not a courtesy. Examples in docstrings under
+`src/g` and pages under `docs/` are executed by `pytest`/`py.test` — the
+doctest flags live in `pyproject.toml`, so there is no separate doctest
+step and a green test run is the proof. `README.md` is not included, so its
+examples are never executed. Which blocks qualify, and the one mistake that
+silently removes a test, are in
+[WRITING.md](WRITING.md#documented-examples-that-run).
+
+Ruff's isort config requires `from __future__ import annotations` in every
+module (`required-imports`, backed by the `FA100` rule) — the linter, not
+this file, catches a missing one. Import stdlib modules by namespace
+(`import typing as t`, `import logging`) rather than `from typing import
+…`; third-party packages may use `from X import Y`. Nothing enforces this
+one — it is a convention, not a lint rule.
+
+Before claiming a test or a gate works, show it failing. A gate that has
+never been red is an assumption.
+
+## Tests
+
+Tests live in `tests/test_cli.py`, parametrized through a
+`CommandLineTestFixture` `NamedTuple`. The autouse `setup` fixture in
+`conftest.py` sets `G_IS_TEST=1` for every test, which makes `run()` return
+the `subprocess.Popen` object instead of `None` so assertions can inspect
+it — outside tests, `run()` always returns `None`.
+
+CLI tests invoke real VCS binaries (at minimum `git`) rather than mocking
+the subprocess call; use `tmp_path` and `monkeypatch` to simulate a
+non-repo directory.
+
+`find_repo_type()` requires a `.git`, `.svn`, or `.hg` **directory**. A git
+worktree checkout's top-level `.git` is a file, not a directory, so
+`test_command_line[g-cmd-inside-git-dir]` and its `--help` sibling fail
+there even though nothing is broken. Work from a normal clone (not `git
+worktree add`) to run the full suite green.
+
+When subprocess output seems swallowed, set `G_IS_TEST=1` and call
+`run(wait=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)` to capture
+it for inspection.
+
+Assert on `caplog.records` attributes, not string matching on `caplog.text`
+— `caplog.record_tuples` cannot see `extra` fields. Scope capture with
+`caplog.at_level(logging.DEBUG, logger="g")` — `g`'s modules log through
+`logging.getLogger(__name__)`, so the logger name is the module's own
+dotted path, `g` at the package root. Filter records rather than index by
+position: `[r for r in caplog.records if hasattr(r, "vcs_cmd")]`.
+
+## Documentation
+
+Build once:
+
+```console
+$ make build_docs
+```
+
+Live-reloading preview at `http://localhost:8034`:
+
+```console
+$ make start_docs
+```
+
+From inside `docs/`, the same tasks are `just html` and `just start`; `just
+--list` in `docs/` shows the rest (`watch`, `serve`, `linkcheck`,
+`doctest`). `make build_docs` and `just html` both wrap
+`sphinx-build`; nothing under `docs/_build` is hand-edited.
+
+`AGENTS.md` and `CLAUDE.md` are excluded from the build
+(`exclude_patterns` in `docs/conf.py`) — they are agent guidance, not site
+pages. `make build_docs` catches a broken cross-reference; the test suite
+does not, so build the docs before committing a documentation change.
+
+## Releasing
+
+Never create tags. Never push tags. The owner handles tagging and tag
+pushes, because a tag triggers the publish workflow. See
+[Release commits](WRITING.md#release-commits).
+
+1. Update `CHANGES` with the release notes.
+2. Bump the version in `src/g/__about__.py` and `pyproject.toml`.
+3. Commit the release files with the subject `Tag v<version>`.
+4. Tag (`git tag v<version>`) and push the branch, then the tag
+   (`git push --tags`).
+5. CI builds and publishes to PyPI automatically over OIDC trusted
+   publishing once the tag lands.
+
+Full detail: [docs/project/releasing.md](../docs/project/releasing.md).
+
+## Pull requests
+
+One subject per pull request. Unrelated cleanup found along the way belongs
+in its own commit, and usually in its own pull request.
+
+Discuss a substantial change via an issue before making it.
+
+Commit format is in [WRITING.md](WRITING.md#commits).
+
+Merge once you have the sign-off of one other developer. If you do not have
+permission to merge, ask a maintainer to merge it for you.
+
+## Decorum
+
+- Participants will be tolerant of opposing views.
+- Participants must ensure that their language and actions are free of
+  personal attacks and disparaging personal remarks.
+- When interpreting the words and actions of others, participants should
+  always assume good intentions.
+- Behaviour which can be reasonably considered harassment will not be
+  tolerated.
+
+Based on [Ruby's Community Conduct Guideline](https://www.ruby-lang.org/en/conduct/).
+
+## Security
+
+This repository has no `SECURITY.md`. Please do not open a public issue for
+a vulnerability — report it privately via [GitHub's security
+advisories](https://github.com/vcs-python/g/security/advisories/new).