Improve first-time contributor onboarding in README with enforceable guidance

README.md

@@ -139,6 +139,33 @@ pip install py3plex[viz]
 pip install py3plex[mcp,algos,viz]
 ```
 
+### Contributing (First PR Quick Path)
+
+If this is your first contribution, use this sequence:
+
+```bash
+# 1) Create local dev environment and install package
+make setup
+make dev-install
+
+# 2) Run formatting and checks before opening a PR
+make format
+make lint
+make test
+```
+
+Helpful commands:
+
+```bash
+make help   # List all project commands
+make ci     # Run lint + tests in CI-style order
+```
+
+Safety notes for contributors:
+- Keep changes focused and add tests next to the feature you modify.
+- Do not add new markdown files unless explicitly requested (enforced by `tests/test_link_checker.py` to prevent documentation drift).
+- Prefer running targeted tests first, then broader checks before opening a PR.
+
 ### MCP Integration (AI Agents)
 
 py3plex provides a Model Context Protocol (MCP) server for integration with AI coding assistants:

tests/test_readme_contributor_onboarding.py

@@ -0,0 +1,41 @@
+"""Tests for contributor onboarding guidance in README."""
+
+from pathlib import Path
+
+import pytest
+
+repo_root: Path = Path(__file__).resolve().parents[1]
+
+
+@pytest.fixture
+def readme_content() -> str:
+    """Return repository README text for onboarding assertions."""
+    return (repo_root / "README.md").read_text(encoding="utf-8")
+
+
+def test_readme_has_first_pr_quick_path_section(readme_content: str):
+    """README should include an explicit first-contribution quick path."""
+    assert "### Contributing (First PR Quick Path)" in readme_content
+    assert "### MCP Integration (AI Agents)" in readme_content
+    quick_path_split = readme_content.split(
+        "### Contributing (First PR Quick Path)", maxsplit=1
+    )
+    assert len(quick_path_split) == 2
+    mcp_split = quick_path_split[1].split("### MCP Integration (AI Agents)", maxsplit=1)
+    assert len(mcp_split) == 2
+    section = mcp_split[0]
+    required_commands = [
+        "make setup",
+        "make dev-install",
+        "make format",
+        "make lint",
+        "make test",
+    ]
+    missing = [command for command in required_commands if command not in section]
+    assert not missing, f"README contributor quick path is missing commands: {missing}"
+
+
+def test_readme_mentions_contributor_safety_policy(readme_content: str):
+    """README should surface key contributor safety constraints."""
+    assert "Do not add new markdown files unless explicitly requested" in readme_content
+    assert "make ci" in readme_content