docs: correct call timeout guidance

[steipete]

Summary

• clarify that server listings default to 30 seconds while calls default to 60 seconds
• document both call-timeout overrides: MCPORTER_CALL_TIMEOUT and --timeout
• add the user-facing changelog credit for @KrasimirKralev

Contributor credit

Maintainer-owned replacement for #230 because its fork does not permit maintainer edits. This commit preserves the original PR commit author's exact credit with:

Co-authored-by: KrasimirKralev <krasi@idrobots.com>

Supersedes #230. Leave #230 open until this replacement lands and the maintainer closes the original PR.

Proof

• formatting, lint, typecheck, and build checks pass
• generated docs site contains the corrected contract in both documentation surfaces
• packed tarball installs in a clean isolated npm consumer with zero audit findings
• packed mcporter call --help exposes --timeout <ms>
• source-blind behavior contract: 4/4 clauses pass; obsolete wording absent
• autoreview: no accepted/actionable findings
• public model identifier audit: pass

[clawsweeper]

Codex review: found issues before merge. Reviewed July 18, 2026, 3:34 PM ET / 19:34 UTC.

Summary
The branch corrects README and CLI-reference guidance to distinguish the 30-second list timeout from the 60-second call timeout, documents both call-timeout overrides, and adds a changelog credit for the superseded contribution.

Reproducibility: not applicable. This PR corrects documentation rather than a runtime defect. The relevant contract is directly verifiable from the current timeout-resolution and call-command source paths.

Review metrics: 1 noteworthy metric.

• Patch scope: 3 files affected; 6 added, 2 removed. Two documentation edits are source-accurate, while the remaining four added lines are the release-owned changelog entry that should not ship in this normal PR.

Root-cause cluster
Relationship: canonical
Canonical: #232
Summary: This PR is explicitly the maintainer-owned replacement for the same documentation correction proposed by the contributor's original PR.

Members:

• superseded: docs: correct call-timeout default (60s, not 30s) #230 - The replacement PR explicitly supersedes the original because its fork does not permit maintainer edits, while preserving the original contributor credit.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🌊 off-meta tidepool
Patch quality: 🦐 gold shrimp
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Remove the CHANGELOG.md hunk and retain the original contributor credit in the commit or PR metadata.

Next step before merge

• The code/docs correction is ready for ordinary maintainer review after the release-owned changelog hunk is removed; this collaborator-owned replacement should not be auto-closed or independently rewritten.

Security
Cleared: The patch changes only Markdown documentation and release-note text; it adds no executable, dependency, credential, workflow, or supply-chain surface.

Review findings

• [P2] Remove the release-owned changelog entry — CHANGELOG.md:5-8

Review details

Best possible solution:

Land the two source-accurate documentation corrections without modifying CHANGELOG.md, while retaining the original contributor credit in the PR or commit metadata rather than release-owned notes.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR corrects documentation rather than a runtime defect. The relevant contract is directly verifiable from the current timeout-resolution and call-command source paths.

Is this the best way to solve the issue?

Yes, after removing the release-owned changelog entry. Updating the two user-facing documentation surfaces to match the existing 30-second list and 60-second call defaults is the narrowest maintainable fix.

Full review comments:

• [P2] Remove the release-owned changelog entry — CHANGELOG.md:5-8
CHANGELOG.md is release-owned under the applicable repository policy, so a normal documentation PR should not add this unreleased release-note entry. Keep the contributor credit in commit/PR metadata and limit this branch to the two documentation corrections.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 710840fb7dd0.

Label changes

Label changes:

• add P3: This is a narrow documentation correctness change with no runtime behavior or user-data impact.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: All changed files are documentation, so external real-behavior proof is not required; source-contract verification is the relevant evidence.

Label justifications:

• P3: This is a narrow documentation correctness change with no runtime behavior or user-data impact.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: All changed files are documentation, so external real-behavior proof is not required; source-contract verification is the relevant evidence.

Evidence reviewed

What I checked:

• Current timeout contract: The supplied current-main evidence identifies DEFAULT_LIST_TIMEOUT_MS = 30_000 and DEFAULT_CALL_TIMEOUT_MS = 60_000; call timeout resolution reads MCPORTER_CALL_TIMEOUT when no valid CLI override is supplied. (src/cli/timeouts.ts:1, 710840fb7dd0)
• CLI call-path contract: The related report ties mcporter call to resolveCallTimeout and its timeout guidance to MCPORTER_CALL_TIMEOUT and --timeout, matching the proposed docs wording. (src/cli/call-command.ts:74, 710840fb7dd0)
• Release-note policy conflict: The PR adds four lines to CHANGELOG.md, while the fully read target AGENTS.md reserves release notes for release ownership and says normal PRs and repair lanes should not edit that file. (CHANGELOG.md:5, 6423f5fa8d18)
• Replacement provenance: The PR body describes this as the maintainer-owned replacement for the original documentation contribution because its fork cannot accept maintainer edits; the related original remains open at the contributor's request until this replacement lands. (README.md:178, 6423f5fa8d18)
• Scope and checks: The supplied PR metadata reports 3 changed files, 6 additions, 2 deletions, a clean merge state, and successful macOS, Ubuntu, and Windows build checks. (6423f5fa8d18)

Likely related people:

• steipete: The PR body identifies this as a maintainer-owned replacement and the current branch commit is authored by steipete; the available review context does not expose deeper current-main author history for the timeout implementation. (role: replacement PR owner; confidence: medium; commits: 6423f5fa8d18; files: README.md, docs/cli-reference.md, CHANGELOG.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.