docs + fix: v1.4.0 documentation overhaul, repaired install paths, CI-verified claims

[celikgo]

The doc set had drifted from the shipped v1.4.0 surface. Three separate tool-reference sections claimed 51 tools while actually listing ~43, Sprint 18's authenticated-session feature had zero skill coverage, and the test/skill/binary counts were stale across four files.

Scope note. The original commit was docs and npm keywords only. Three later commits
(see Install paths repaired below) added source, test, workflow and tooling changes, so
that no longer describes this PR.

Skills: 17 → 20

New

Skill	Job
testing-web-authenticated-sessions	The storageState capture/replay workflow — Mode A capture (headed, with a manual MFA pause), Mode B replay via storage_state_path / --storage-state / the scenario storageState field. Plus login-wall detection mid-run, expiry and re-capture, and secret hygiene.
running-web-ci-suites	Suite files as a real CI gate — --workers, --shard, --tag, the exit-code contract, JUnit wiring, artifact upload, and a complete GitHub Actions example.
troubleshooting-webmobai-setup	A webmobai-doctor-driven decision tree for browser / engine / Lighthouse / AI-key / storageState / Gatekeeper failures.

Updated — all 17 existing skills had drifted claims corrected against source, and gained auth handoffs, the versioned-baseline tools, the opt-in AI tools, and the v1.4.0 assert_url + scenario-runner semantics changes.

.claude/skills/README.md was rebuilt: 20-skill index, updated decision tree, new Preflight / Authenticated sessions / AI layer conventions, and a tool table whose category counts sum to exactly 51.

Docs

• USER_MANUAL.md §7 rebuilt as a per-tool table — all 51 tools, one row each, with a column for whether a launched browser is required (+538 lines).
• New: docs/AUTHENTICATION.md (426), docs/CI.md (477), docs/README.md (doc index).
• docs/SCENARIO_FORMAT.md: storageState, saveStorageState, pauseForManual.
• FEATURES.md: Sprint 18 sections, the 20-skill list, corrected limitations.
• ROADMAP.md: Sprint 18 entry + What's next.
• CONTRIBUTING.md: skill authoring, and a "keeping docs honest" checklist of every place each count is asserted.
• README.md / mcp-server/README.md: accurate counts, docs index, auth example.

Counts corrected throughout

51 tools across 16 tool files · 7 binaries · 214 tests across 26 files (was 200 / 23) · 20 skills (FEATURES.md said 8).

Verification run against the final tree

• All 20 skill frontmatter names match their directory name.
• All 51 tools appear exactly once, no duplicates or omissions, in each of the three tool references; every category count sums to 51.
• 0 dangling relative links across 32 files.
• Every JSON and YAML code block parses.

One product finding (not fixed here)

pauseForManual never actually pauses under either shipped CLI. scenario-cli.ts:84 and suite/runner.ts:105 both hardcode headless: true, and scenario/runner.ts:143-151 makes the step a warn-and-continue no-op when headless. A scenario doing pauseForManual → saveStorageState therefore writes an unauthenticated session file and records the run as green. The step only works for programmatic BrowserManager + runScenario callers.

The new auth skill documents this as a trap to avoid rather than a recommended path, but the real fix is either a --headed flag on those CLIs or making the step fail loudly in headless. Worth a follow-up issue.

🤖 Generated with Claude Code

---

Install paths repaired, and every published number made CI-verified

Added after the original doc overhaul. Two of the four documented install paths were dead, and
the numbers the README advertises were unenforced prose.

What the investigation actually found

The npm publish job already existed. release.yml has carried a publish-npm job since the
v1.4.0 hardening. It ran on the v1.4.0 tag and failed in 26s with
E404 Not Found - PUT https://registry.npmjs.org/webmobai-mcp. A 404 on a PUT is npm's
signature for a token that cannot authenticate, so NPM_TOKEN is invalid, expired, or
read-only. This was a credential problem, not a packaging one.

webmobai-mcp --help would have hung even once published. src/index.ts had no argv
handling at all — it connected the stdio MCP transport and blocked forever on stdin. The command
the README teaches for verifying an install could never have worked.

All three headline numbers were already correct. 51 tools, 7 binaries, 214 tests each
recounted true, so none were "fixed". They are now verified rather than trusted.

Changes

Install paths

• index.ts gains --help / --version, plus 5 subprocess tests in which a regression hangs
  and the timeout is the assertion. Also drops a hardcoded v1.2.0 startup banner that had
  drifted from the real 1.4.0, by reading the version from package.json.
• release.yml publishes with --provenance, guards that the tag matches package.json, and
  smoke-tests the built entrypoint before publishing.
• server.json + an mcpName in package.json, staged for the official MCP Registry. mcpName
  has to be in the published tarball — the registry reads it from there to verify ownership, and
  npm versions are immutable — so it lands before the first publish, not after.

Links

• github.com/modelcontextprotocol/sdk 404s; corrected to typescript-sdk.
• Placeholder domains in the skill docs (foo.com, bar.com, x.com) are real registrable
  domains a link checker will chase. Replaced with RFC 2606 reserved names.
• New docs-links workflow (lychee), modeled on the salman repo's. It found 3 real dead links
  on its first run and now checks 250 with zero dead.

Numbers

• scripts/check-doc-claims.mjs recounts tools, tool files, binaries, tests, test files, skills
  and the eval rates from the tree, checking 29 claims across 3 files. Verified to fail on
  injected drift — it caught this PR's own test additions, which is why the README now reads
  219 tests / 27 files.

Designed for agents

• docs/DESIGNED_FOR_AGENTS.md — why a selector miss returns a prior fingerprint, ranked
  candidates and page-state triage, with a transcript captured from the running code rather than
  illustrated.

• An 18-case eval measures it, running in CI and gating at an 80% floor:

  Top-1 recovery: 86.7%  (13/15)
  Top-3 recovery: 93.3%  (14/15)
  Correct abstention: 66.7%  (2/3)
  Overall: 83.3%  (15/18)
  

  The corpus deliberately includes cases the tool fails, and the doc names all three — a
  suite containing only passes measures the author's taste in examples, not the algorithm. The
  eval runs against dist/, not src/: an early 0% reading was esbuild's keepNames helper
  leaking a __name reference into page.evaluate, a property of the loader rather than the
  product. The shipped build is sound.

Hygiene

• SECURITY.md — what storageState files actually contain (live session tokens), that they are
  never transmitted, and the disclosure path.
• CODE_OF_CONDUCT.md (Contributor Covenant 2.1).
• Social preview: a split frame — the request in plain English beside the real browser run with
  the assertion passing. HTML source kept in-repo so the image is reproducible. It carries no
  counts, because a number baked into a PNG is the one claim check-doc-claims cannot reach.
• Release matrix extended to Linux and Windows, on ubuntu-22.04 rather than latest so the
  AppImage does not silently raise the glibc floor.

Two CI fixes that were not planned

The link checker failed on its first real run, twice, and both causes were worth fixing rather
than merging past:

1. A circular failure. It flagged the blob/main links in mcp-server/README.md pointing at
   docs/AUTHENTICATION.md and docs/CI.md — files added on this branch, so they 404 until it
   merges, and the check blocks the merge that fixes it. Those links cannot become relative
   (that README renders on npmjs.com, where ../docs/CI.md resolves to nothing), so this repo's
   own blob URLs are remapped onto the checked-out working copy. That tests the invariant worth
   testing — the file this link points at exists in this repository — before and after merge.
2. A flake. [ERROR] https://tauri.app/ | Connection failed, on a link that is fine;
   re-running passed unchanged. lychee defaults to 128 concurrent requests, which produces
   connection resets indistinguishable from dead links. Concurrency capped at 16, harder
   retries, real user agent. A 404 still fails the build.

Still open after this merge

• The npm publish itself — blocked on npm credentials on the publishing machine. Nothing has
  been published.
• The homepage field — points at the npm package once it exists.
• The social preview upload — GitHub has no API for it; docs/assets/README.md has the path.
• Registry submissions — staged in docs/MCP_DIRECTORY_SUBMISSIONS.md and deliberately not
  sent.
• The Linux and Windows release jobs are unproven. The matrix, the webkit2gtk-4.1
  dependencies and the shell: bash fix are written from the documented requirements, but
  release.yml only fires on v*, so the first real proof is the next tag.