docs: correct call-timeout default (60s, not 30s)

[KrasimirKralev]

What Problem This Solves

Two docs claim the call timeout defaults to 30 s, but the code defaults it to 60 s. Only the list timeout is 30 s.

In src/cli/timeouts.ts:

const DEFAULT_LIST_TIMEOUT_MS = 30_000;
const DEFAULT_CALL_TIMEOUT_MS = 60_000;
...
export const LIST_TIMEOUT_MS = parseTimeout(process.env.MCPORTER_LIST_TIMEOUT, DEFAULT_LIST_TIMEOUT_MS);

export function resolveCallTimeout(override?: number): number {
  if (typeof override === 'number' && Number.isFinite(override) && override > 0) return override;
  return parseTimeout(process.env.MCPORTER_CALL_TIMEOUT, DEFAULT_CALL_TIMEOUT_MS);
}

resolveCallTimeout is what mcporter call uses (src/cli/call-command.ts:74), and the command's own timeout error message names the same env var: "Override MCPORTER_CALL_TIMEOUT or pass --timeout to adjust." (src/cli/call-command.ts:533).

Two doc sites are wrong:

1. README.md — "Timeouts default to 30 s; override with MCPORTER_LIST_TIMEOUT or MCPORTER_CALL_TIMEOUT…" lumps both env vars under a single 30 s figure, so a reader expects mcporter call to abort at 30 s when it actually runs to 60 s.
2. docs/cli-reference.md — "--timeout <ms> – override call timeout (defaults to CALL_TIMEOUT_MS)" references a symbol that does not exist in the codebase; the real knob is the MCPORTER_CALL_TIMEOUT env var (default 60 s).

Why This Change Was Made

Docs-correctness only. The diff touches two Markdown lines and no production code, config, or defaults:

• README now states listing defaults to 30 s and calls default to 60 s, keeping both env-var override names.
• The CLI reference now names the actual env var (MCPORTER_CALL_TIMEOUT) and the real 60 s default instead of the non-existent CALL_TIMEOUT_MS.

User Impact

No runtime change. Readers relying on the docs now get the correct call-timeout default (60 s) and the correct env-var name to override it, so timeout expectations for mcporter call match observed behavior.

Evidence

Claims verified against current main (710840f):

• src/cli/timeouts.ts:1-2 — DEFAULT_LIST_TIMEOUT_MS = 30_000, DEFAULT_CALL_TIMEOUT_MS = 60_000.
• src/cli/timeouts.ts:23 — call default falls back to MCPORTER_CALL_TIMEOUT / DEFAULT_CALL_TIMEOUT_MS (60 s).
• src/cli/call-command.ts:74 — mcporter call resolves its timeout via resolveCallTimeout.
• src/cli/call-command.ts:533 — user-facing timeout error names MCPORTER_CALL_TIMEOUT, matching the corrected docs.

git diff --check is clean; the change is limited to README.md and docs/cli-reference.md.

Generated by Claude Code

---

Generated by Claude Code

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 17, 2026, 7:25 AM ET / 11:25 UTC.

Summary
Updates README.md and docs/cli-reference.md to distinguish the 30-second listing timeout from the 60-second call timeout and document the call-timeout environment variable.

Reproducibility: not applicable. This PR corrects documentation rather than reporting a runtime failure; source inspection is sufficient to verify the timeout contract.

Review metrics: 1 noteworthy metric.

• Documentation scope: 2 files; 2 additions, 2 deletions. The patch is narrowly scoped and changes no runtime, configuration, dependency, or build behavior.

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:

• Rewrite the CLI-reference line to state the 60-second default first and identify the environment variable and flag as overrides.

Next step before merge

• [P1] One mechanical documentation wording correction is needed before normal PR validation.

Security
Cleared: The diff changes only two Markdown lines and introduces no code execution, dependency, permissions, secrets, or supply-chain surface.

Review findings

• [P2] Describe the environment variable as an override — docs/cli-reference.md:51

Review details

Best possible solution:

Keep the README change and rewrite the CLI-reference entry as “defaults to 60 s; override with MCPORTER_CALL_TIMEOUT or --timeout.”.

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

Not applicable: this PR corrects documentation rather than reporting a runtime failure; source inspection is sufficient to verify the timeout contract.

Is this the best way to solve the issue?

No, not quite: distinguishing 30-second listings from 60-second calls is correct, but the CLI-reference wording should identify MCPORTER_CALL_TIMEOUT as an override rather than a default.

Full review comments:

• [P2] Describe the environment variable as an override — docs/cli-reference.md:51
MCPORTER_CALL_TIMEOUT is not itself the default: resolveCallTimeout parses it as an optional override and otherwise falls back to 60,000 ms. Since this PR is correcting the timeout documentation, please say “defaults to 60 s; override with MCPORTER_CALL_TIMEOUT or --timeout” so the replacement text does not introduce a new ambiguity.
  Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.97

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 low-risk documentation correctness fix with one small wording defect remaining.
• 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: Every changed file is documentation, so external real-behavior proof is not required.

Label justifications:

• P3: This is a low-risk documentation correctness fix with one small wording defect remaining.
• 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: Every changed file is documentation, so external real-behavior proof is not required.

Evidence reviewed

Acceptance criteria:

• [P1] ./runner git diff --check.
• [P1] ./runner pnpm check.
• [P1] ./runner pnpm build.
• [P1] ./runner pnpm test.

What I checked:

• Runtime default: Current main defines separate 30,000 ms listing and 60,000 ms call defaults, with MCPORTER_CALL_TIMEOUT parsed as an override for calls. (src/cli/timeouts.ts:1, 710840fb7dd0)
• Call path: The call command obtains its timeout through resolveCallTimeout, confirming that the 60-second call default is the relevant documented behavior. (github.com) (src/cli/call-command.ts:74, 710840fb7dd0)
• User-facing override guidance: The timeout error directs users to override MCPORTER_CALL_TIMEOUT or pass --timeout, which treats the environment variable as an override rather than the default itself. (github.com) (src/cli/call-command.ts:533, 710840fb7dd0)
• Remaining documentation defect: The proposed CLI-reference wording says the call timeout “defaults to MCPORTER_CALL_TIMEOUT, or 60 s,” incorrectly presenting the environment variable as a default value instead of an override source. (docs/cli-reference.md:51, c0d50db041d4)
• Feature history: The changelog records the call timeout as a default configurable through MCPORTER_CALL_TIMEOUT or --timeout, and later records the default explicitly as 60 seconds. (github.com) (CHANGELOG.md)

Likely related people:

• steipete: The timeout behavior appears in the project's early release history and subsequent timeout propagation work associated with the repository's principal historical contributor; exact introducing-commit attribution could not be recovered from the available read-only history surface. (role: feature and release-history owner; confidence: medium; files: src/cli/timeouts.ts, src/cli/call-command.ts, 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.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: docs: correct call-timeout default (60s, not 30s) This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.