Two changes requested by the user:
1. Fold the hand-holding quickstart tutorial into README §3 (both
languages). Delete docs/quickstart.md and docs/quickstart.zh-CN.md.
Remove them from all 5 validator DOCS lists, README §6 doc index,
and charter §7 boundary table. The tutorial now lives as
README §3.0–§3.11: prerequisites, create Telegram bot, find chat id,
get JMAP credentials, run backend, sign in, fill config, register
callbacks, enable processing, verify, schedule drain, troubleshoot.
2. Replace 'gateway'/'网关' with 'load balancer'/'负载均衡器' across
all markdown (README, docs/, AGENTS.md, cloudflare-worker/README).
Also fix 4 markdown anchor links whose heading slugs changed.
Also fix charter §8 '18 safe routes' → '19' (was missed in the
earlier reference.md fix).
GATE-DOCS 6/6 PASS (71 anchors, 727 path-refs, 455 sec-refs).
New docs/quickstart.md and docs/quickstart.zh-CN.md walk a human operator from
zero to the first notification: create a Telegram bot via BotFather, find the
chat id, get a Stalwart app password, provision Redis, deploy the container,
sign in with CONFIG_ENCRYPTION_KEY, fill the business config, register
callbacks, enable processing, verify end-to-end, and schedule the cron drain.
Every claim was verified against the code:
- healthz is static 200 'ok'; /ready returns 503 until all upstreams
reachable, 200 with per-component booleans
- admin session TTL = 1800s (30 min) in state.rs
- first save must be complete -> 422 (is_complete in config.rs)
- 409 conflict on revision mismatch
- secrets are write-only (Option<SecretString>, never echoed)
- /worker and /reconcile return 204 on success, 503 when disabled
- webhook secret mismatch returns 401 (not 403)
- search triggers: 搜索/查找/检索 + /search command only
- cron-drain.sh uses MW_APP_URL (req), MW_WORKER_TOKEN (req),
MW_RECONCILE_TOKEN (opt)
Registered both files in all 5 validator DOCS lists (audit_paths globs
automatically). Added rows to README §6 and charter §7 in both languages.
Added discoverable links from README §3 to the quickstart.
GATE-DOCS 6/6 PASS (71 anchors, 735 path-refs).
Reframe the Cloudflare Worker gateway across the entry points where a
reader forms an impression of it, in both languages:
- README §2 / §5 (en+zh): the gateway is optional and exists because
Cloudflare's Load Balancer product is not on the free plan. Drop the
comparison row that listed 'only the 19 safelisted paths' against
'every route' as if the safelist were a benefit; replace it with
backend reachability, which is identical either way, and move the
route-count fact to its own neutral row. Add one sentence to §5 that
the gateway is outside the secret boundary.
- deployment.md §10 (en+zh): purpose is load balancing, not protection;
no intent to hide or harden the backends, no access control at the
edge, the allowlist is not a firewall.
- cloudflare-worker README (en+zh): new 'why it exists' / 'why it is
not a security feature' block, plus a 'not a security layer' bullet.
Drop 'access-hiding capability' from the non-capabilities list, since
claiming invisibility as something we refuse to provide implies it is
the interesting axis.
- reference.md §4 / §9.2 (en+zh) and deployment.md zh §2: stop saying
bootstrap and /debug/* are 'not exposed' / 'kept off the public path'.
They are simply not in the route set, which is why a request to the
Worker never reaches them — reachable at the backend's own address
either way.
- charter ARCH-LB-WORKER (en+zh): 'only external entrance' -> 'only
*registered* entrance', which is what C-LB-SINGLE-REG-URL actually
says, and backends stay directly reachable.
SAF-LB-PASSTHRU already records the security-side invariant (no auth
or body rewriting, backend may be directly connected to the public
network), so no new stable ID is needed. No code changes; GATE-DOCS
6/6.
Root README gains §2 "Two ways to run it": a side-by-side table of
Form A (backend origin only) against Form B (behind the Cloudflare Worker
gateway) — what answers, failover, the callback URL to register, the
reachable route surface, which health endpoint to watch, and the docs to
read. Late in the switch: registration is idempotent and re-adding retires
the previous subscription, so the switch is one SPA field, not a migration;
nothing secret moves to the gateway; /api/bootstrap and /debug/* stay
origin-only either way. Later sections renumbered, and the monitoring
paragraph now points at the gateway aggregate GET /healthz-worker instead
of the origin-passthrough /healthz.
cloudflare-worker/README.md rewritten as the canonical English version and
cloudflare-worker/README.zh-CN.md added as its translation, covering the
route safelist (19 paths with per-path methods), the timeout/retry budget
with per-route overrides, bounded failover, the two health endpoints,
callback registration, config, local verification, deploy, and the design
invariants.
Both fixes along the way:
- README.zh-CN said the startup env block has 2 required + 2 optional
variables; the table has 3 rows, 2 required + 1 optional.
- docs/charter.md §8 / registry list now names the zh-CN twin next to the
gateway README.
scripts/docs_check gains the new file in validate_docs, check_tables,
audit_anchors and audit_anchor_semantics so it is checked like every other
document. check_sec_refs resolves §-refs against the document being scanned
when a basename is shared: README.md exists both at the repo root and under
cloudflare-worker/, and the basename-keyed heading map silently dropped one
of them. The gate was passing for the wrong reason before.
GATE-DOCS 6/6 clean: 72 anchors, 454 section refs, 727 path refs.
audit_anchor_semantics still reports the same 7 pre-existing candidates,
none in the new or edited files.
anonsaber