Add anonymization developer README notes

README.md

@@ -46,6 +46,12 @@ Detector-specific extension notes live in
 [docs/pii-detector-playbook.md](docs/pii-detector-playbook.md), and editable backlog
 seed data is available at [examples/challenge_backlog.json](examples/challenge_backlog.json).
 
+Developer notes:
+
+- [src/makeaivisible_anonymizer/README.md](src/makeaivisible_anonymizer/README.md)
+  explains the service package and request flow.
+- [examples/README.md](examples/README.md) explains the synthetic examples.
+
 ### Run locally
 
 ```bash

examples/README.md

@@ -0,0 +1,16 @@
+# Anonymization Examples
+
+This folder contains synthetic examples only.
+
+- `request.json`: a sample `/anonymize` request for local testing.
+- `challenge_backlog.json`: editable notes for the 12 MVP challenge areas.
+
+Run the service locally, then submit the example:
+
+```bash
+curl -s http://127.0.0.1:8000/anonymize \
+  -H 'content-type: application/json' \
+  --data @examples/request.json
+```
+
+Do not place real contributor exports in this folder.

src/makeaivisible_anonymizer/README.md

@@ -0,0 +1,27 @@
+# Anonymization Service Package
+
+This package is the first privacy boundary after an upload. It accepts conversation
+messages, redacts supported identifiers, and returns anonymized messages plus a redaction
+report.
+
+## File Map
+
+- `main.py`: FastAPI app, `/health`, and `/anonymize`.
+- `models.py`: request and response schemas, validation limits, and output shapes.
+- `limits.py`: request body size guard before JSON parsing.
+- `detectors.py`: active regex detectors and documented detector gaps.
+- `redaction.py`: matching, overlap handling, replacement labels, and redaction counts.
+
+## Request Flow
+
+1. `limits.py` rejects oversized HTTP bodies.
+2. `models.py` validates message roles, content lengths, and unknown fields.
+3. `main.py` loops through messages and calls `redaction.py`.
+4. `redaction.py` uses `detectors.py` to replace matched identifiers.
+5. The response includes generated `conversation_id`, redacted messages, and a report.
+
+## Where To Add New PII Work
+
+Start with tests in `tests/test_redaction.py`, then update `detectors.py`. Do not add
+real names, real schools, real addresses, or real conversations as fixtures. Use synthetic
+examples only.