docs: describe the API surface the README actually reaches

[dmccoystephenson]

Summary

• The "📦 Features (MVP Scope)" bullets are rewritten so each one describes the capability set
  actually reachable through the controllers. Renaming (entities, grids, environments), the
  unassigned-entity query, the unoccupied-locations-in-a-grid query, neighbor lookup, occupancy
  reporting, entity listing at a location, and the adjacency-checked move were all absent.
• The Environment bullet's "update (including renaming)" is narrowed to "rename": renaming is the
  only update the environment surface offers, so the broader wording promised more than exists.
• The "📂 Project Structure" listing now names PLANNING.md, REBUILD_PLAN.md, and diagrams/
  alongside MVP.md and openapi/, with each described from what the file/directory holds
  (diagrams/ holds a draw.io class-usage diagram and its rendered PNG, not Mermaid sources).

Every claim was checked against src/main/java/preponderous/viron/controllers/*.java rather than
against docs/MVP.md, as the issue's acceptance criteria ask. The two documents agree: all 36
routes are present in both.

Test plan

• No source, test, or configuration file is touched — the diff is README.md only.
• Each rewritten bullet traced to its handler method: updateEntityName, updateGridName,
  updateEnvironmentName, getEntitiesNotInAnyLocation, getUnoccupiedLocationsInGrid,
  getNeighbors, isLocationOccupied, getEntityIdsAtLocation, addEntityToLocation,
  moveEntityToLocation, removeEntityFromLocation, removeEntityFromCurrentLocation.
• The docs/ listing verified against the directory as it stands on main.
• CI (Java build/tests plus the Python client suite) green on the head commit.

Issues left for a later cycle

The rest of the open backlog was not picked up, for reasons recorded here rather than as comments
on each issue:

• One entity per location is enforced only by the move endpoint, so a concurrent placement still walks around it #213 — whether one entity per location is an invariant is a product decision that changes the
  API contract; it is stated in the issue as two coherent, opposed answers and wants a human choice
  before any code moves.
• Nothing bounds how long a request waits for a row lock, and the pool is not sized against it #212 — lock timeouts and pool sizing touch compose.yml and application configuration, which
  are do-not-auto-merge paths for this loop and larger than a polish-sized change.
• The Python client cannot be installed or imported as a package; its modules import through the repository path #209 — packaging the Python client is a build-surface change (requirements.txt, a new
  project file, import paths across the client and its tests) and does not batch with a docs fix.
• Wire OpenAPI-first codegen / spec-drift guard (rebuild-plan hygiene gap) #130 — OpenAPI-first codegen / spec-drift guard adds a CI workflow, also a do-not-auto-merge
  path.

Closes #215

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric

• Scope: PASS — git diff --name-only origin/main...HEAD returns README.md alone; the diff is
  13 added and 3 removed lines, all inside the two sections The README's feature list understates the implemented API surface #215 names.
• Tests-new: not applicable — no public method or function is added by this PR.
• Tests-fix: not applicable — The README's feature list understates the implemented API surface #215 is a documentation defect, not a behavioral one; no
  production code path changes, so there is nothing a stash-and-run could make fail.
• Sibling structure: PASS — the three added lines in the project-structure listing reuse the
  │ ├── prefix, the comment column, and the two trailing spaces (Markdown hard break) of the
  MVP.md line above them; verified with a trailing-whitespace grep rather than by eye.
• Sibling renames: not applicable — no identifier is renamed.
• Docs: PASS — docs/MVP.md and docs/openapi/viron-api.json already carried the full 36-route
  surface, so this PR moves the third document onto them rather than the reverse; tickets.md,
  docs/PLANNING.md, docs/REBUILD_PLAN.md, and the Postman collection describe endpoints and
  process, none of which this diff touches.
• Issue resolution: PASS — both acceptance criteria are met. Each bullet was traced to a handler
  in src/main/java/preponderous/viron/controllers/, and the docs/ entry now names all five
  things the directory holds.
• CI: PASS — build, python-client (3.8), and python-client (3.12) all green on head
  e2a8f9f (run 34452272169).
• DTO boundary: not applicable — no controller is touched.
• Spec alignment: PASS — no endpoint is added or changed; the README was checked against the
  controllers rather than against the spec, and the two were found to agree.
• Java/Python parallelism: not applicable — no model or service behavior changes.
• Override correctness: not applicable — no @Override is added.

Findings folded in from the diff read

• README.md:64-66 — the three location bullets were first written in a conversational voice
  ("Ask which entities a location holds") that no other bullet in the section uses. Fixed in
  e2a8f9f to the imperative "Retrieve / report / find" the surrounding bullets share.
• README.md:53 — the Environment bullet's original "update (including renaming)" was narrowed to
  "rename", against the issue's own statement that this bullet needed no change. updateEnvironmentName
  is the only update the environment surface offers, so the broader phrasing promised a general
  update capability that does not exist. Where the issue and the source disagreed, the source was
  taken as authoritative.
• Not fixed here, worth noting for a later cycle: README.md:159 tells a reader to
  pip install -r requirements.txt and run pytest against a client imported through the
  repository path (src.main.python.preponderous.viron...). That wording is accurate today but is
  exactly what The Python client cannot be installed or imported as a package; its modules import through the repository path #209 proposes to change, so it will need revisiting when the client becomes an
  installable package.

Anchor scope

CI's Java build job does not execute anything this PR changes, and neither do the two
python-client jobs — a documentation-only diff has no automated coverage by construction. The
green run establishes only that nothing was broken. The verification that matters here is the
manual trace of each bullet to its handler method, recorded in the PR body.

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson