Skip to content

docs: adopt GeneFoundry README Standard v1 #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
berntpopp merged 2 commits into from
Jul 14, 2026
Merged

docs: adopt GeneFoundry README Standard v1 #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3afd4bd
docs: refactor README to GeneFoundry README Standard v1
berntpopp Jul 14, 2026
b3b30d6
docs: correct false config facts and machine-check the env table
berntpopp Jul 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ LOGGING__FORMAT=text
CORS__ALLOW_ORIGINS=["http://localhost:3000","http://localhost:8080"]
CORS__ALLOW_METHODS=["GET","POST","PUT","DELETE","OPTIONS"]
CORS__ALLOW_HEADERS=["*"]
CORS__ALLOW_CREDENTIALS=true
CORS__ALLOW_CREDENTIALS=false

# STRING API Configuration
STRINGDB_API__BASE_URL=https://version-12-0.string-db.org/api
Expand Down Expand Up @@ -52,4 +52,4 @@ SECURITY__RATE_LIMIT_WINDOW=60

# MCP Configuration
MCP__PATH=/mcp
MCP__SERVER_NAME=StringDB-Link Server
MCP__SERVER_NAME=stringdb-link
4 changes: 2 additions & 2 deletions .env.npm.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ LOGGING__FORMAT=json
CORS__ALLOW_ORIGINS=["https://stringdb.yourdomain.com"]
CORS__ALLOW_METHODS=["GET","POST","PUT","DELETE","OPTIONS"]
CORS__ALLOW_HEADERS=["*"]
CORS__ALLOW_CREDENTIALS=true
CORS__ALLOW_CREDENTIALS=false

# STRING API Configuration
STRINGDB_API__BASE_URL=https://version-12-0.string-db.org/api
Expand Down Expand Up @@ -57,4 +57,4 @@ SECURITY__RATE_LIMIT_WINDOW=60

# MCP Configuration
MCP__PATH=/mcp
MCP__SERVER_NAME=StringDB-Link Server
MCP__SERVER_NAME=stringdb-link
20 changes: 20 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,9 @@ Required checks before claiming completion:

- `make ci-local`

One-time local setup: `make install`, then `uv run pre-commit install` to install the
git hooks (Ruff, mypy, and the per-file line budget).

Useful focused commands:

- `make install`
Expand All @@ -48,6 +51,7 @@ Useful focused commands:
- `make lint`
- `make lint-fix`
- `make lint-loc`
- `make lint-readme`
- `make typecheck`
- `make typecheck-fast`
- `make test`
Expand All @@ -72,6 +76,22 @@ Useful focused commands:
- Keep FastAPI route behavior covered by route tests and service behavior
covered by unit tests.

## Documentation Discipline

`README.md` follows the **GeneFoundry README Standard v1** and is machine-checked by
`make lint-readme` (`scripts/check_readme.py`, copied verbatim across the fleet). It is
the front door, not the manual: fixed section order, a 200-line hard ceiling, no
hand-typed counts or scores. Reference docs live in `docs/`:

- `docs/configuration.md` - environment variables and request guards
- `docs/deployment.md` - transports, entry points, Docker, reverse proxy
- `docs/architecture.md` - module layout, REST-to-MCP generation, REST examples
- `docs/data.md` - STRING sources, caching, licence, citation

Add a tool, update the README's `## Tools` table: `tests/unit/test_readme_tools.py`
asserts the table equals the registered tool surface exactly, and CI fails otherwise.
Do not move operator or reference detail back into the README; extend `docs/` instead.

## File Size Discipline

Hard cap: **600 lines per Python module** in `stringdb_link/`, `server.py`, and
Expand Down
7 changes: 5 additions & 2 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.PHONY: help install lock upgrade sync format format-check lint lint-ci lint-fix lint-loc typecheck typecheck-fast typecheck-stop typecheck-fresh test test-fast test-unit test-integration test-cov test-all check ci-local precommit clean dev mcp-serve mcp-serve-http docker-build docker-up docker-down docker-logs
.PHONY: help install lock upgrade sync format format-check lint lint-ci lint-fix lint-loc lint-readme typecheck typecheck-fast typecheck-stop typecheck-fresh test test-fast test-unit test-integration test-cov test-all check ci-local precommit clean dev mcp-serve mcp-serve-http docker-build docker-up docker-down docker-logs

DOCKER_COMPOSE := $(shell if command -v docker >/dev/null 2>&1 && docker compose version >/dev/null 2>&1; then echo "docker compose"; elif command -v docker-compose >/dev/null 2>&1; then echo "docker-compose"; else echo "docker compose"; fi)

Expand Down Expand Up @@ -36,6 +36,9 @@ lint-fix: ## Lint and apply safe fixes
lint-loc: ## Enforce per-file line budget (see AGENTS.md "File Size Discipline")
uv run python scripts/check_file_size.py

lint-readme: ## Enforce the GeneFoundry README Standard v1
uv run python scripts/check_readme.py

typecheck: ## Type check package
uv run mypy stringdb_link server.py mcp_server.py

Expand Down Expand Up @@ -89,7 +92,7 @@ test-all: test-cov ## Alias for full test run with coverage

check: format lint ## Format and lint

ci-local: format-check lint-ci lint-loc typecheck-fast test-fast ## Run fast local CI-equivalent checks
ci-local: format-check lint-ci lint-loc lint-readme typecheck-fast test-fast ## Run fast local CI-equivalent checks

precommit: ci-local ## Run checks expected before commit

Expand Down
Loading