Refs #426: Clarify authenticated attempt examples

[Juanpablo24-06]

Summary

• Update the advisory attempt examples in docs/api-examples.md to include the required GitHub-authenticated browser session cookie.
• State that unauthenticated attempt registration and release return 401, matching app/auth.py and app/bounty_attempts.py.

Refs #426

Evidence

• Code checked: app/bounty_attempts.py wires attempt registration/release through require_github_login; app/auth.py returns 401 when no GitHub login is present.
• Docs alignment checked against docs/agent-guide.md, which already shows the session cookie for the same authenticated attempt flow.

Checks

• ./.venv/bin/python scripts/docs_smoke.py
• git diff --check

Summary by CodeRabbit

• Documentation
  • Updated API example documentation to clarify authentication requirements for attempt registration and release operations.
  • Authenticated requests now explicitly require a browser session cookie from the same GitHub account; unauthenticated requests return 401.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 025e3147-8a13-42c9-96e0-fa4e7a96522c

📥 Commits

Reviewing files that changed from the base of the PR and between d8532d4 and c64d31e.

📒 Files selected for processing (1)

• docs/api-examples.md

---

📝 Walkthrough

Walkthrough

Updates the Advisory Attempt Reservations API example documentation to clarify that authenticated attempt registration and release require a GitHub-authenticated browser session cookie for the same account. Unauthenticated requests return 401. Both affected curl commands are amended to include the cookie flag.

Changes

API Example Documentation Update

Layer / File(s)	Summary
Advisory Attempt Reservations authentication documentation docs/api-examples.md	Authentication guidance is added to clarify that authenticated attempts require a GitHub-authenticated browser session cookie for the same account, and unauthenticated requests return 401. The curl examples for attempt registration and release are updated to include the -b "<browser-session-cookie>" flag.

Possibly related PRs

• ramimbo/mergework#431: Updates documentation for advisory attempt reservations endpoints to clarify authentication requirements and adjust curl examples.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: clarifying authenticated attempt examples in response to issue #426.
Description check	✅ Passed	The description covers all required sections: Summary, Evidence, and Checks. It explains what was changed, why, and what was verified.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Mergework Public Artifact Hygiene	✅ Passed	PR adds API docs with no investment, price, cash-out, or payout claims. MRWK is native coin; private keys kept local; future bridges require discussion.
Bounty Pr Focus	✅ Passed	PR diff matches stated file (docs/api-examples.md only, +6/-0), evidence from app/bounty_attempts.py and app/auth.py is verified, scope is focused with no unrelated changes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Baijack-star]

Reviewed PR #542 at head c64d31e for the authenticated attempt examples slice.

Evidence checked:

• Diff is limited to docs/api-examples.md and adds the browser-session-cookie flag to the register/release attempt curl examples.
• app/auth.py require_github_login returns 401 when the mrwk_user GitHub session cookie is missing, matching the new unauthenticated-request wording.
• app/bounty_attempts.py wires both POST /api/v1/bounties/{bounty_id}/attempts and POST /api/v1/bounty-attempts/{attempt_id}/release through Depends(require_github_login), while the GET attempts list remains public.
• docs/agent-guide.md already documents the same authenticated browser session cookie for this flow, so this PR makes the API examples consistent with the agent guide.

Validation run locally on the PR branch:

• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• uv run --extra dev ruff check docs/api-examples.md -> All checks passed (no Python files under that path)
• git diff --check origin/main...HEAD -> clean

Assessment: no blocker found in this docs-only slice; it matches the implementation and existing agent-guide contract. No private cookies, tokens, wallet material, production mutation, payout guarantees, liquidity/exchange/off-ramp claims, or private data were used.

[tinyopsstudio]

Reviewed PR #542 at c64d31ee9bdebdeead9d2b6b77a55454360de950 for the authenticated attempt examples in docs/api-examples.md.

Evidence checked:

• inspected docs/api-examples.md, docs/agent-guide.md, app/auth.py, and app/bounty_attempts.py;
• confirmed the docs now add the browser-session-cookie note before the write examples and add -b "<browser-session-cookie>" to both attempt registration and release curl snippets;
• confirmed app/bounty_attempts.py wires both POST attempt routes through Depends(require_github_login);
• confirmed app/auth.py returns HTTP 401 when the signed GitHub session cookie is absent, while the read-only GET attempts example stays unauthenticated.

Validation:

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_bounty_attempts.py tests/test_docs_public_urls.py -q -> 30 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest -q -> 414 passed
• uv run --extra dev ruff check docs/api-examples.md tests/test_bounty_attempts.py tests/test_docs_public_urls.py -> passed
• git diff --check origin/main...HEAD -> clean

Assessment: no blocker found. The docs change is small and aligns the API examples with the existing authenticated write-route behavior.

[eliasx45]

Reviewed current head c64d31ee9bdebdeead9d2b6b77a55454360de950 for the authenticated attempt API examples.

No blocker found. The docs-only change aligns docs/api-examples.md with the implementation: the read-only attempts list remains unauthenticated, while both write routes are wired through Depends(require_github_login) and therefore return 401 without a signed GitHub browser session. The added cookie note also matches the existing agent-guide examples.

Validation run from the checked-out PR branch:

git diff --check origin/main...HEAD
# clean

.\.venv\Scripts\python.exe scripts\docs_smoke.py
# docs smoke ok

.\.venv\Scripts\python.exe -m pytest tests\test_bounty_attempts.py tests\test_docs_public_urls.py -q
# 30 passed

.\.venv\Scripts\python.exe -m ruff check docs\api-examples.md tests\test_bounty_attempts.py tests\test_docs_public_urls.py
# All checks passed

.\.venv\Scripts\python.exe -m pytest -q
# 414 passed

GitHub PR checks are green for this head: CodeRabbit status and the quality/readiness/docs/image workflow are successful.

[ramimbo]

Bounty #426 is now filled and closed, so this PR is not currently payable under that bounty. Leaving mrwk:needs-info here; please retarget only if a future live bounty explicitly covers this work, or confirm that you want it considered as a non-bounty contribution.

[barnacleagent-svg]

Verdict: APPROVED

Scope: Clarifies authenticated attempt examples in docs/api-examples.md. Adds cookie note for authenticated requests and updates curl examples with -b flag.

Checklist:

• Diff: +5/-0, documentation-only
• Clearer auth flow documentation
• Tests pass

Conclusion: Helpful docs clarification. Ready to merge.

[wangedmund77-cmyk]

Reviewed current head c64d31ee9bdebdeead9d2b6b77a55454360de950 for bounty #578.

Evidence checked:

• Inspected the docs-only diff in docs/api-examples.md.
• git diff --check origin/main...origin/pr/542 returned clean.
• Ran uv run pytest tests/test_docs_public_urls.py -q on the PR head: 23 passed.
• GitHub mergeability is clean/MERGEABLE.

No blocker found. The added note makes the authenticated attempt examples clearer without changing public API semantics or adding any private credential material.