Skip to content

fix: stabilize hosted documentation follow-ups - #405

Merged
jlitola merged 11 commits into
mainfrom
jlitola/stable-documentation-followups
Sep 18, 2026
Merged

jlitola merged 11 commits into
mainfrom
jlitola/stable-documentation-followups

Conversation

@jlitola

@jlitola jlitola commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

Summary

  • omit observed search bounds from automatic CLI and MCP follow-ups for hosted/crawled HTTP(S) documentation_page targets
  • forward page URLs and emitted heading fragments unchanged while preserving repository-document snapshot ranges and explicit caller-supplied read bounds
  • update durable CLI/MCP guidance and add regression plus smoke coverage for publication replacement semantics

Verification

  • bun test — 4,826 pass
  • bun run typecheck
  • bun run format:check
  • bun run lint — passes with 8 pre-existing warnings in repository-target.ts
  • bun run build
  • bun run plugins:check
  • bun run validate:packages
  • bun run smoke:cli:built
  • bun run smoke:mcp:built
  • source CLI unauthenticated and MCP registration smokes
  • Opus review loop — final round clean

Live evidence

After resolving a local keychain prompt, a live source search for routing against site:expressjs.com returned hosted documentation_page hits with observed locator ranges and bounds-free generated followUp values. Human-readable CLI output displayed the exact hosted target without coordinates. An unbounded live read of the returned https://expressjs.com/en/5x/guide/routing/ target then returned the current page from line 1 through its reported total; the 16,278-line aggregate target also completed through source and built CLIs with valid JSON.

After the Express corpus refresh, a live route methods search emitted https://expressjs.com/en/5x/guide/routing/#route-methods with search evidence lines 56–66. The generated follow-up preserved that fragment exactly and omitted bounds. Executing it returned lines 56–112 beginning at ## Route methods, confirming the complete heading subtree rather than replaying the narrower search coordinates.

The full authenticated MCP smoke progressed through live package calls but stopped on an unrelated pkg_upgrade_review success assertion before reaching its documentation block. The focused real-site search-to-read path is verified; a full live MCP-suite pass is not claimed.

Targeted agent evaluation was also attempted. Claude's isolated harness was not logged in. Codex invoked search and docs_list, then timed out after 302 seconds while those service calls remained in progress; its available tool-call and metrics artifacts were inspected, with no final or isolation artifact produced.

Scope

No backend, remote server, release, deployment, retry, snapshot, compatibility, or historical-storage changes are included.

Record the verified shared formatter boundary, mutable hosted-document contract, snapshot preservation, and end-to-end acceptance workflow.
Drop search evidence ranges from generated follow-ups for mutable hosted documentation URLs while preserving repository snapshot ranges and explicit caller bounds. Update durable CLI, MCP, and Agent Skill guidance for the current-content contract.
Describe mutable hosted targets, snapshot-addressed repository docs, and full heading-subtree reads in both current and deprecated CLI help surfaces.
Document heading-subtree semantics across MCP and Agent Skill surfaces, remove vacuous CLI text assertions, and validate bounds-free hosted follow-ups in live MCP smoke coverage.
Teach the shared smoke corpus to return hosted documentation evidence and prove the live assertion rejects generated follow-ups that replay search bounds.
Use the explicit Express documentation site and follow one documented search continuation before requiring hosted evidence, with coverage for the in-progress response shape.
Key the hosted-doc smoke continuation on the completion flag and model the required empty results array in its in-progress fixture.
Capture the completed implementation, validation, smoke limitations, and clean review evidence before draft PR delivery.
@jlitola jlitola added fix documentation Improvements or additions to documentation labels Sep 17, 2026
Close the implementation plan with the delivered draft PR while preserving the explicit merge and release boundary.
Replace the earlier keychain-blocked smoke limitation with the successful real-site search-to-read evidence and retain the unrelated full-suite limitation.
@jlitola
jlitola marked this pull request as ready for review September 18, 2026 05:56
Capture the refreshed Express corpus evidence showing exact fragment forwarding and bounds-free heading-subtree reads.
@jlitola
jlitola merged commit 27f57d4 into main Sep 18, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation fix

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant