docs: adopt GeneFoundry README Standard v1#29
Merged
Conversation
The README had become an unversioned operator manual (289 lines) that no
reader scanned and no CI verified — and parts of it had rotted: it advertised
env vars that the nested Pydantic settings no longer accept
(STRINGDB_BASE_URL, CACHE_IDENTIFIER_TTL, LOG_LEVEL), a serverInfo.name
("StringDB-Link Server") that the ratified conformance gate contradicts, a
required_score example (400) outside the model's 0.0-1.0 bounds, and clone
URLs for an org that does not host this repo.
Rewrite it to the standard's fixed shape (119 lines): four machine-maintained
badges, lead paragraph, research-use callout above the fold, Why, Quick start,
Tools, Data & provenance, Documentation, Contributing, License.
Nothing is deleted — content is relocated, and the destinations are created in
this commit:
- docs/configuration.md — every env var with its CORRECT nested name
(STRINGDB_API__*, CACHE__*, CORS__*, ...), the exact Host/Origin request
guards (wildcards rejected; add the proxy hostname), the CORS
credentialed-wildcard startup failure, the two-tier cache TTLs, log
redaction, and the MCP identity contract.
- docs/deployment.md — the two console scripts, the tri-modal transport table
with the http-serves-no-/mcp footgun, health endpoints, Docker/Compose,
reverse-proxy rules, Claude Desktop stdio config, and the outstanding
operator action from SECURITY.md (secret scanning / push protection).
- docs/architecture.md — module layout, how FastMCP.from_fastapi generates the
tool surface from route operation_ids (and which routes are excluded), the
MCP hardening layers, the federation contract, and the REST API examples.
- docs/data.md — the STRING v12.0 pin and why it is load-bearing, the upstream
endpoint map, TTL rationale, the 1 req/s courtesy rate that must not be
bypassed, caller_identity, the CC BY 4.0 data licence, and the citation.
- AGENTS.md — pre-commit hook install, make lint-readme, and documentation
discipline so the README does not re-bloat.
Stale facts are corrected against the code rather than carried over; marketing
prose (emoji feature lists, unverifiable performance claims, a readthedocs site
that does not exist) is dropped.
Two gates keep this true:
- scripts/check_readme.py (verbatim fleet copy) — length, section order, badge
row, research-use callout, link integrity, hand-typed derived facts. Wired
into the Makefile as lint-readme and added to ci-local.
- tests/unit/test_readme_tools.py — asserts the README's ## Tools table equals
the server's registered tools exactly, enumerating them through the same
`facade` fixture test_tool_names.py uses. Verified to fail when a row drifts.
make ci-local is green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The README Standard v1 refactor introduced factual errors in docs/configuration.md — the exact rot the standard exists to prevent. Corrections (verified against the live settings model): - CORS__ALLOW_ORIGINS default is ["http://localhost:3000","http://127.0.0.1:3000"], not []. The dev defaults are inert in production (the ALLOWED_ORIGINS request guard rejects those origins before CORS applies), but the documented fact was false. - LOGGING__FORMAT default is json, not text. - README claimed configuration.md documents "every environment variable"; it omitted 8 of 48 (HEALTH_CHECK__*, STRINGDB_API__USER_AGENT/ENDPOINTS, the LOGGING__FILE_* rows). The claim is now true rather than softened. - STRINGDB_API__CALLER_IDENTITY default is exact, not elided. Sources of truth fixed, not just described: - .env.example / .env.npm.example shipped MCP__SERVER_NAME="StringDB-Link Server", so `cp .env.example .env` silently broke the ratified serverInfo.name federation contract that the conformance gate and the router registry both assert. They now ship stringdb-link. - Both templates shipped CORS__ALLOW_CREDENTIALS=true on a backend documented as unauthenticated-by-design ("off by design"), contradicting the doc and the fleet CORS standard. Now false. tests/unit/test_config_docs_contract.py pins all of it: the doc table must be exhaustive over the settings model and every documented default must equal the code default; env-template keys must be real settings (extra="ignore" drops typos silently) or compose-interpolated; templates may not override serverInfo.name or enable credentialed CORS. Mutation-checked — reinstating the [] default or dropping a row fails the suite. make ci-local green (452 passed); scripts/check_readme.py exits 0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adopts README Standard v1 (genefoundry-router#64).
README: 289 → 120 lines.
A fleet-wide audit scored all 22 READMEs across ten dimensions. Quality correlated inversely with length (Spearman ρ = −0.79): the five shortest averaged 7.2/10, the five longest 4.0/10. The fleet failed on exactly three dimensions — badges (2.0/10; 18 of 22 repos had none), signal-to-noise (4.5), scannability (4.7). Long READMEs had become unversioned operator runbooks that no reader scans and no CI verifies.
What changed
Why→Quick start→Tools→Data & provenance→Documentation→Contributing→License.Python 3.12+·CI·Conformance·License. The two middle ones are live GitHub Actions status, so they cannot rot into a lie.docs/(destination files created in this PR, so no link dangles).Enforcement
scripts/check_readme.py(vendored verbatim from the router) wired intomake ci-localaslint-readme: length ceiling, section order, exact badge lines, the research-use callout, link integrity, and no hand-typed derived facts.tests/unit/test_readme_tools.py: the## Toolstable is machine-verified against the server's actually-registered tools. Add a tool without a README row and CI fails.Review pass
Every repo was adversarially reviewed by an independent agent against the source. Real defects were found and fixed here — not just formatting: false parameter contracts, env vars documented as live that the code silently ignores, a wrong
serverInfo.name, incomplete "documents every variable" claims. A README that lies is worse than one that is long.make ci-local: green.🤖 Generated with Claude Code
https://claude.ai/code/session_013Pz2byzxG2oNxJBAtSWCJQ