ax-grep 0.0.0 → 0.1.1

package/docs/README.md

@@ -0,0 +1,19 @@
+# Documentation
+
+Start here when README is too small for the detail you need.
+
+| Goal | File |
+| --- | --- |
+| Install the Codex skill prompt | [../skills/ax-grep-cli/SKILL.md](../skills/ax-grep-cli/SKILL.md) |
+| Use CLI search and `--agent` output | [cli-agent.md](./cli-agent.md) |
+| Build a minimal agent handoff loop | [agent-handoff.md](./agent-handoff.md) |
+| Use as a server/library package | [library-api.md](./library-api.md) |
+| Inject into WebViews or browser pages | [library-api.md](./library-api.md#browser-injection) |
+| Check readiness before promotion | [agent-readiness.md](./agent-readiness.md) |
+| Track current progress and next work | [progress.md](./progress.md) |
+| Review feature details | [features.md](./features.md) |
+| Run benchmarks and comparisons | [benchmarks.md](./benchmarks.md) |
+| Read current `agent-browser` comparison notes | [comparison-baseline.md](./comparison-baseline.md) |
+
+The root README should stay short: skill install first, server library usage
+second, WebView/browser usage third, then links.

package/docs/agent-handoff.md

@@ -0,0 +1,95 @@
+# Agent Handoff Loop
+
+`--agent` returns compact JSON with `agent.executor`, `agent.handoff`, `agent.next`,
+`pageCheck`, `verification`, and source evidence. Executors can usually switch
+only on `agent.executor.decision`.
+
+## Decisions
+
+| Decision | Meaning |
+| --- | --- |
+| `return` | Read the named payload path and answer from current evidence. |
+| `execute` | Run `commandArgs` and inspect the next `ax-grep` payload. |
+| `browser` | Open the URL in a live browser and optionally rerun with captured HTML. |
+| `stop` | Stop because the page or query cannot be usefully advanced. |
+
+`commandArgs` always starts with `ax-grep`. Callers using `execFile` can pass
+`commandArgs.slice(1)` back to the binary.
+
+## Resource Safety
+
+Run executor loops sequentially. Do not fan out `ax-grep`, comparison, or
+browser-backed checks. Before and after browser work, run `pnpm check:processes`
+and clean up any project-owned `agent-browser` or Chromium process.
+
+## Minimal Executor
+
+```ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { AgentExecutorStep, AgentJsonEnvelope } from "ax-grep";
+
+const execFileAsync = promisify(execFile);
+
+async function runAxGrep(args: string[]): Promise<AgentJsonEnvelope> {
+  const { stdout } = await execFileAsync("ax-grep", args);
+  return JSON.parse(stdout);
+}
+
+async function inspectWithAxGrep(urlOrQuery: string) {
+  let payload = await runAxGrep([urlOrQuery, "--agent"]);
+
+  for (let iteration = 0; iteration < 4; iteration += 1) {
+    const step: AgentExecutorStep = payload.agent.executor;
+
+    if (step.decision === "return") {
+      return step.readValue?.value ?? payload;
+    }
+
+    if (step.decision === "stop") return payload;
+
+    if (step.decision === "execute" && step.commandArgs) {
+      payload = await runAxGrep(step.commandArgs.slice(1));
+      continue;
+    }
+
+    if (step.decision === "browser") {
+      return openInAgentBrowser(step.url);
+    }
+
+    throw new Error(step.reason);
+  }
+
+  return payload;
+}
+```
+
+## Output Shape
+
+The full JSON is intentionally compact but can still be large. Read these
+fields first:
+
+- `agent.handoff`: shortest next-step instruction.
+- `agent.executor`: single-field executor step with command, read, or browser fields.
+- `agent.next`: canonical loop payload with command, read target, or browser step.
+- `verification`: quickest answer for `--find` checks.
+- `pageCheck`: title, evidence, actions, barriers, forms, sources, and metadata.
+- `agent.citations` and `agent.answerEvidence`: evidence ready for final answers.
+
+`--agent-brief` keeps `agent.executor` and `agent.handoff` as the primary loop
+surface and omits larger planning fields. When there are alternate search
+results or source links, brief mode places executable choices on
+`agent.handoff.resultChoices` and `agent.handoff.sourceChoices`; each choice
+uses raw `commandArgs` so callers can run it without rebuilding a command.
+Search choices keep snippets, answer handoffs keep selected evidence text, and
+form/action-target read handoffs keep URL templates, fields, selectors, and
+methods. Browser-interaction targets keep barrier `path`/`text` and selector
+when available. Source-link actions keep `sourceLinkRef` back to
+`pageCheck.sourceLinks[n]`.
+
+For browser-rendered pages, capture HTML in the agent browser and rerun:
+
+```sh
+ax-grep https://example.com --html-file captured.html --agent
+cat captured.html | ax-grep https://example.com --stdin --agent
+```

package/docs/agent-readiness.md

@@ -0,0 +1,38 @@
+# Agent Readiness Matrix
+
+This project goal is not just raw accessibility-tree parity. `ax-grep` should
+let subagents search, inspect pages, decide the next step, and recover from thin
+or blocked pages with less guesswork than an `agent-browser snapshot` alone.
+
+## Evidence Map
+
+| Requirement | Current evidence | Completion note |
+| --- | --- | --- |
+| CLI agent usefulness stays above the readiness floor for every gate-included target. | `averageCliAgentScore` and `minCliAgentScore` must stay at or above `0.8`; `averageAgentExecutorScore` and `minAgentExecutorScore` must stay at or above `0.995`; raw accessibility overlap metrics remain diagnostic only. | Covered by `compare:gate` and comparison-gate tests. |
+| Search agents can open the best or alternate result without rebuilding commands. | `agent.resultChoices`, `openResult`, `commandArgs`; covered by `tests/cli.test.ts` and `averageSearchResultActionScore`. | Covered by focused tests and comparison gate metrics. |
+| Page-check agents can read structured evidence instead of raw tree text. | `pageCheck.contentEvidence`, citations, `agent.readTargets`, `bestReadTarget`; covered by read-target, citation, answer-plan, evidence metadata, readability reason, and consistency gates. | Covered by tests and static comparison scoring. |
+| Source-link follow-up keeps a stable pointer back to the source array. | `sourceLinkRef` on actions, compact actions, page steps, and text output; covered by CLI and public type tests. | Covered for JSON and text output. |
+| Brief handoff remains executable for subagent loops. | `agent.executor`, `agent.handoff`, `commandArgs`, `readValue`, `resultChoices`, `sourceChoices`; covered by brief executor/handoff tests and gates. | Covered for common search, page, source, form, action-target, and diagnostic cases. |
+| Thin, blocked, or browser-needed pages expose why browser capture is needed. | `needsBrowserHtml`, `browserHtml`, `signals`, `qualityGates`, barriers, and browser retry actions; covered by browser-need, browser-html, signal, and quality-gate scores. | Covered by non-browser fixtures and comparison scoring. |
+| Hidden page signals that are absent from accessibility trees stay discoverable. | Hydration, API, config, policy, schema, resource, media, citation, code-block, and action-target summaries are scored through hidden-signal, hidden-command, response-metadata, count, consistency, and read-target gates. | Covered by static extraction tests; real browser parity still depends on comparison runs. |
+| A minimal real page can use static agent handoff without browser capture. | `pnpm readiness:real-page-smoke` checks `https://example.com` with `--agent-brief`, `canUseFetchedHtml=true`, `needsBrowserHtml=false`, and named semantic roles. | Covered as a smoke gate; broader real-page and `agent-browser` comparison remains. |
+| A minimal `agent-browser` comparison set has stable named-role overlap. | `pnpm readiness:agent-browser-smoke` checks `https://example.com` for exact overlap, `https://books.toscrape.com/` for catalog-page floors, `https://news.ycombinator.com` for link-heavy listing floors, and `https://www.gov.uk/foreign-travel-advice` for government index/search-page floors. | Covered as a four-target smoke gate; broader `agent-browser` comparison remains. |
+| Text-heavy documents separate structural readiness from raw StaticText volume. | `pnpm readiness:agent-browser-text-heavy-smoke` checks Korean Wikipedia with structural content, action, navigation, and text-recall fields. | Covered as a separate smoke gate; not part of the main overlap gate. |
+| Operational safety prevents host overload during validation. | `AGENTS.md`, `vitest.config.ts`, `docs/benchmarks.md`, `docs/comparison-baseline.md`, the `agent-browser` comparison lock, and finally-based session close helpers in browser comparison scripts. | Commands must still be run one at a time, with `pnpm check:processes` before and after risky browser-backed runs. |
+
+## Completion Gate
+
+Do not call this objective complete from unit tests alone. A completion audit
+must inspect:
+
+- `pnpm exec tsc --noEmit`
+- `pnpm readiness:audit`
+- `pnpm readiness:real-page-smoke`
+- `pnpm readiness:agent-browser-smoke`
+- focused non-browser Vitest coverage for changed contracts
+- `pnpm compare:gate <latest comparison report>` for saved comparison output
+- process cleanup before and after browser-backed comparison commands
+- current docs proving README details remain split into `docs/`
+
+Browser-backed comparison suites must run sequentially. If the host is already
+under browser load, postpone them rather than starting another comparison.

package/docs/benchmarks.md

@@ -0,0 +1,123 @@
+# Benchmarks and Comparison Gates
+
+Resource safety:
+
+- Run these commands one at a time. Do not parallelize `compare:static*`,
+  `compare:tokens*`, or browser-backed tests.
+- `compare:static*` may launch `agent-browser` and Chromium. Check for existing
+  browser work before starting, and confirm processes are cleaned up afterward.
+- Use `pnpm readiness:audit` before claiming the agent-readiness objective is
+  complete. It checks that the single-worker validation rules, fixture gate,
+  comparison gate, process checker, and README/docs split are still wired in.
+- Use `pnpm readiness:real-page-smoke` for the smallest real-page check. It
+  fetches `https://example.com` with `--agent-brief` and does not launch
+  Puppeteer or `agent-browser`.
+- Use `pnpm readiness:search-smoke` for the smallest real search check. It
+  runs `--search "ax-grep npm" --engine auto --agent-brief`, verifies engine
+  attempts, and does not launch Puppeteer or `agent-browser`.
+- Use `pnpm readiness:agent-browser-smoke` for the smallest `agent-browser`
+  comparison set. It checks `https://example.com` and
+  `https://books.toscrape.com/`, `https://news.ycombinator.com`, and
+  `https://www.gov.uk/foreign-travel-advice`; run `pnpm check:processes`
+  before and after it.
+- Use `pnpm readiness:agent-browser-text-heavy-smoke` only when checking the
+  text-heavy document policy. It checks Korean Wikipedia separately from the
+  main smoke because strict StaticText overlap is tracked apart from structural
+  content readiness.
+- Use `pnpm check:processes` before and after browser-backed comparison runs.
+- If several target sets are needed, run them sequentially and save each output
+  separately.
+
+```sh
+pnpm benchmark:agent-cost
+pnpm compare:sample
+pnpm compare:static:fixtures
+pnpm compare:static:fixtures:gate
+pnpm readiness:audit
+pnpm readiness:real-page-smoke
+pnpm readiness:search-smoke
+pnpm readiness:agent-browser-smoke
+pnpm readiness:agent-browser-text-heavy-smoke
+pnpm check:processes
+pnpm compare:static https://example.com https://news.ycombinator.com
+pnpm compare:tokens https://example.com https://news.ycombinator.com
+pnpm compare:static:agent
+pnpm compare:static:korea-social
+pnpm compare:tokens:korea-social
+pnpm compare:static:china-japan
+pnpm compare:tokens:china-japan
+pnpm compare:gate /tmp/ax-grep-agent.json /tmp/ax-grep-tokens.json
+```
+
+The comparison scripts compare `ax-grep` output with `agent-browser snapshot`
+output and score the CLI `--agent` summary. The score covers `agent`,
+`pageCheck`, `searchResults`, structured evidence, readability, source link
+quality, verification status, recommended actions, and next steps.
+
+Token comparisons estimate prompt cost for compact tree text and agent JSON
+payloads. See [comparison-baseline.md](./comparison-baseline.md) for the current
+baseline run.
+
+## Agent Cost Benchmark
+
+`pnpm benchmark:agent-cost` compares `ax-grep --agent-brief` with
+`agent-browser snapshot --compact` on local fixture pages. It runs cases
+sequentially, writes `tmp/benchmarks/agent-cost.json`, and closes the browser
+session after each case.
+
+Latest local run:
+
+| Case | ax-grep peak RSS | agent-browser peak RSS | RAM multiple | ax-grep decision tokens | agent-browser tokens | Token multiple |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| content-page | 80.0 MB | 906.4 MB | 11.3x | 631 | 1,903 | 3.0x |
+| challenge-page | 72.1 MB | 1,404.7 MB | 19.5x | 910 | 241 | 0.3x |
+
+Summary: average RAM reduction was 15.4x. The content fixture used 3.0x fewer
+decision tokens when the agent reads the compact handoff instead of a browser
+snapshot. The challenge fixture is primarily a memory/browser-avoidance win:
+`ax-grep` detects hCaptcha markers and returns an explicit browser handoff
+without launching Chromium.
+
+Search, social, challenge, and volatile targets may be diagnostic-only and
+excluded from gate averages. Check each run's `included` and `excluded` counts
+before treating an average as release-gating coverage.
+
+`compare:static:fixtures:gate` is the non-browser smoke gate: it uses synthetic
+HTML fixtures only, so it should not fetch remote pages or launch
+`agent-browser`. Use `compare:static:fixtures` when you need the JSON report.
+
+`readiness:real-page-smoke` is the smallest remote-page gate. It checks that
+`--agent-brief` can use fetched HTML on `https://example.com` without requesting
+browser capture.
+
+`readiness:agent-browser-smoke` is the smallest browser-backed comparison gate.
+It runs `pnpm compare` for `https://example.com` and
+`https://books.toscrape.com/`, `https://news.ycombinator.com`, and
+`https://www.gov.uk/foreign-travel-advice`, requires `agent-browser`
+snapshots, and enforces per-target overlap/readiness floors. Treat it like
+other browser-backed work: one command at a time, with process checks before
+and after.
+
+`readiness:agent-browser-text-heavy-smoke` is a separate browser-backed
+comparison for text-heavy document pages. It requires Korean Wikipedia to keep
+usable action/navigation/structural-content recall while still reporting strict
+text recall separately.
+
+`compare:gate` checks saved JSON output from `compare:static*` and
+`compare:tokens*`. Static gates require executor, handoff, browser-advantage,
+search/page decision, and action-list scores to stay near 1.0 with no
+gate-included challenge, shell, or over-collected classifications. Token gates
+require the compact agent payload average to stay cheaper than the browser
+reference after thin browser snapshots are excluded.
+
+Current suites include:
+
+- static HTML vs browser snapshots
+- fixture-only agent readiness smoke checks
+- agent executor regression targets for `averageAgentExecutorScore`
+- fixture-backed search open, search refine, and browser HTML retry recovery
+- CLI agent summary scoring for `pageCheck`, sources, readability, and actions
+- token-cost comparison for compact tree prompts and agent JSON prompts
+- Korean forum/search/social targets
+- Chinese and Japanese wiki/news/forum/search targets
+- challenge and volatile-page diagnostics

package/docs/cli-agent.md

@@ -0,0 +1,194 @@
+# CLI and Agent Mode
+
+`ax-grep` fetches a URL, extracts a semantic page summary, and prints compact
+text by default.
+
+```sh
+ax-grep https://example.com
+ax-grep https://example.com --json
+ax-grep https://example.com --json --summary
+ax-grep https://example.com --links-only
+ax-grep https://example.com --max-tree-lines 80
+ax-grep https://example.com --mode interactive --exclude-boilerplate
+ax-grep https://example.com --timeout 30000 --user-agent "my-agent/1.0"
+```
+
+By default the CLI fetches static HTML with `impit`, which uses browser-like
+HTTP/TLS fingerprints. If `impit` cannot load or the request fails before a
+response is returned, ax-grep falls back to Node's built-in fetch. Pass
+`--fetcher node` to force the built-in fetch path.
+
+If fetched HTML shows hCaptcha, reCAPTCHA, or Cloudflare challenge markers, the
+agent payload reports `needs-browser` with a provider-specific
+`browserHtmlReasonCode` and a browser-capture follow-up command.
+
+## Search
+
+```sh
+ax-grep --search "agent browser accessibility tree"
+ax-grep --search "ax-grep npm" --engine bing --links-only
+ax-grep --search "ax-grep npm" --engine bing --lang en --region US
+ax-grep --search "ax-grep npm" --open-result best --json
+```
+
+- `--search` tries DuckDuckGo, Bing, and StartPage by default.
+- `--engine <name>` forces one search engine.
+- `--open-result <n|best>` fetches a ranked result in the same command.
+- `--lang` and `--region` make locale-specific searches reproducible.
+
+## Agent Routing
+
+Use `--agent` when another program needs the next step instead of raw tree text.
+The response includes compact `agent`, `pageCheck`, `verification`, search, and
+warning fields.
+
+Read these first:
+
+- `agent.status`: `ready`, `choose-result`, `verify`, `needs-browser`, or `error`.
+- `agent.staticReadiness*`: fetched-HTML usability status, machine-readable
+  reason code, prose reason, and the static path to read first.
+- `agent.executor`: one-field executor step with decision, command/read/browser fields.
+- `agent.executorActionName`, `agent.executorOperation`, and related `executor*`
+  shortcuts: top-level mirror of the next executable step, loop decision, and
+  target, terminal/continue flags.
+- `agent.handoff`: the shortest executor handoff for the next step.
+- `agent.handoffActionName`, `agent.handoffOperation`, and related `handoff*`
+  shortcuts: top-level mirror of the brief handoff contract, loop decision, and
+  target, terminal/continue flags.
+- `agent.runbook*`: top-level loop reason, mode, confidence, answer status, and
+  iteration shortcuts for `--agent-brief` routing without expanding `runbook`.
+- `agent.next`: canonical loop payload with command, read target, or browser step.
+- `agent.next*`: canonical next-step action, execution, command, read, and URL shortcuts.
+- `agent.page*`: title, canonical URL, language, author, dates, and structured-data type shortcuts.
+- `agent.expectedOutcome*` and `agent.executionPlan*`: top-level success
+  condition and execution-plan shortcuts for fast routing without expanding
+  nested objects.
+- `agent.sourceSearch*`: opened-result query, locale, verification queries, engine,
+  selected/alternate result, and command shortcuts.
+- `agent.searchDecision*` and `agent.pageDecision*`: top-level routing decisions and command/read pointers.
+- `agent.answerPlan`, `agent.citations`, and `agent.answerEvidence`: final answer evidence.
+- `agent.answerPlanStatus`, `agent.answerPlanConfidence`, and related `answer*`
+  shortcuts: top-level answer readiness, next action, command, and citation routing.
+- `agent.topCitation*`: first citation item for fast source quality checks.
+- `agent.topAnswerEvidence*`: first answer evidence item for fast citation/read routing.
+- `agent.topVerificationFoundQuery` and `agent.topVerificationMissingQuery`: first
+  matched or missing `--find` query for fast verification routing.
+- `agent.readTargets`, `agent.topReadTarget*`, and `agent.bestReadTarget*`: ranked paths to inspect and the
+  best path's count/primary flags.
+- `agent.bestHiddenReadTarget*`: best hidden metadata path to inspect first.
+- `agent.topHiddenSignal*`: first hidden metadata/API/config/provenance signal.
+- `agent.semantic*`: compact semantic tree counts and direct paths to top
+  heading/landmark/named role/interactive/focusable/link/button/image/table/list/form-field/description/value/relation/choice/state/unavailable entries.
+  `semanticOutline` and `semanticTopOutline*` preserve heading/landmark page flow
+  plus parent landmark context for fast structural routing. `semanticKeyboardShortcut*` exposes keyboard shortcut,
+  access key, and tabindex hints. Field shortcuts include placeholder/autocomplete/inputmode
+  and aria label/description references. `semanticTopInPageLink*` exposes skip
+  links and same-page anchors. Relation shortcuts include resolved target role/selector when available.
+  State shortcuts also expose parsed top-state fields such as `semanticTopStateCurrent`,
+  `semanticTopStateControls`, `semanticTopStateHaspopup`, and `semanticTopStateInvalid`.
+- `agent.barrierCount` and `agent.topBarrier*`: primary login, paywall,
+  challenge, consent, age, or geo barrier details for browser routing.
+- `agent.dataTableCount`, `agent.faqCount`, `agent.codeBlockCount`,
+  `agent.resourceCount`, `agent.mediaCount`, `agent.sectionCount`,
+  `agent.breadcrumbCount`, `agent.paginationCount`, `agent.tocCount`,
+  `agent.embedCount`, `agent.transcriptCount`, `agent.authorLinkCount`,
+  `agent.provenanceCount`, `agent.offerCount`, `agent.datasetCount`,
+  `agent.identityCount`, `agent.timelineCount`, `agent.contactPointCount`, and
+  matching `top*` fields: first structured page item shortcuts with direct paths/selectors when available.
+- `agent.bestStructuredReadTarget*`: highest-priority structured content path to
+  read before scanning all `readTargets`.
+- `agent.resultChoices` and `agent.sourceChoices`: ranked links to open.
+- `agent.topResultChoice*`: first search-result candidate with URL, rank,
+  command args, source quality, freshness/relevance, match, and sitelink hints.
+- `agent.topSourceChoice*`: first source-link candidate with URL, command args, source type, source hints, and source score.
+- `agent.topFormChoice*` and `agent.topActionTargetChoice*`: first executable
+  form/action target templates, query inputs, submit text, and first-field hints.
+- `agent.topChoice*`: first executable result, source, form, or action-target choice.
+- `agent.topAction*`: first action candidate with execution, priority, command/read, and URL shortcuts.
+- `agent.primarySourceLinkRef`: primary source-link action's `pageCheck.sourceLinks[n]`.
+- `agent.alternativeAction*`: first non-primary action candidate, including source,
+  execution mode, command args, URL, and source-link reference when available.
+- `agent.recommended*`: selected search result metadata and command args.
+- `agent.signals` and `agent.qualityGates`: compact diagnostics.
+- `agent.topSignal*` and `agent.topQualityGate*`: first quality signal and gate
+  shortcuts for fast accept/block routing.
+- `agent.problemSignal*` and `agent.failingQualityGate*`: first blocking or
+  warning reason, severity, and score without scanning diagnostic arrays.
+- `agent.topDiagnostic*`: first diagnostic code, severity, and message.
+
+In `--agent-brief`, the stable executor surface is `agent.executor` plus
+`agent.handoff`. Brief handoff keeps loop metadata, target URL, priority,
+reason, and executable `resultChoices` or `sourceChoices` when alternates are
+available. It also keeps the details needed to act without reopening the full
+payload: search snippets, selected answer evidence text, form/action URL
+templates, field selectors, methods, browser barrier targets, and source-link
+`sourceLinkRef` pointers.
+
+Agent actions use an `execution` discriminator:
+
+- `run-command`: execute `commandArgs` with `execFile`-style argument passing.
+- `read-current`: read the current payload path named by `readFrom`.
+- `interact-browser`: use a live browser, then optionally rerun with captured HTML.
+
+Generated commands preserve fetch and search context such as `--lang`,
+`--region`, `--find`, `--timeout`, `--user-agent`, `--fetcher`, and `--agent`.
+Text output also prints `executor*` lines for the same next-step fields.
+
+## Find and Verification
+
+Use repeatable `--find <text>` with any page or search result page to verify a
+term or phrase.
+
+```sh
+ax-grep https://example.com --agent --find "documentation examples"
+ax-grep --search "OpenAI API docs" --find "Responses API" --agent
+```
+
+JSON output adds `finds` and `verification`. `verification.status` is the
+quickest page-check answer:
+
+- `matched`: every requested phrase was found.
+- `partial`: some phrases were found.
+- `missing`: none were found.
+- `not-requested`: no `--find` query was supplied.
+
+When evidence is missing, `verification.recommendedAction` points to the next
+useful move, such as opening a source link, opening an alternate original SERP
+result, retrying with browser-captured HTML, or broadening the search.
+
+## Browser-Captured HTML
+
+The default URL path uses `impit` with Node fetch fallback. It does not execute
+page JavaScript.
+When a page is challenged, logged-in, or JavaScript-rendered, let a browser
+controller capture the HTML and pass it back through the same CLI.
+
+```sh
+ax-grep https://example.com --html-file captured.html --agent
+cat captured.html | ax-grep https://example.com --stdin --agent
+```
+
+If fetched HTML has no inspectable content, JSON mode returns a structured error
+and warning. Use `--html-file` or `--stdin` for rendered fallback HTML.
+
+## Page Summary Fields
+
+`kind` classifies the page as `search-results`, `content-page`,
+`interactive-page`, `blocked-page`, `empty`, or `page`.
+
+`pageCheck` is the higher-level inspection summary agents should read before the
+raw tree. It includes title, canonical URL, main heading, content evidence,
+source-like external links, actions, confidence, readability, and follow-up
+actions.
+
+Useful `pageCheck` groups include:
+
+- Content and verification: `contentEvidence`, `dataTables`, `sections`, `toc`, `codeBlocks`, `citations`, `faqs`, and `breadcrumbs`.
+- Interaction and recovery: `barriers`, `forms`, `actionTargets`, `pagination`, `recommendedAction`, and `nextSteps`.
+- Hidden app/page state: `hydration`, `apiEndpoints`, `clientState`, `runtime`, `config`, `appHints`, and `mobileHints`.
+- Metadata and provenance: `topics`, `keyValues`, `metaFacts`, `provenance`, `httpPolicies`, `schemaFacts`, `offers`, `identities`, `datasets`, `timeline`, `contactPoints`, and `authorLinks`.
+- Media and resources: `media`, `resources`, `embeds`, and `transcripts`.
+
+These fields expose details often absent from an accessibility tree, including
+JSON-LD facts, head metadata, API endpoints, app configuration, policy
+directives, feed/license/resource links, and mobile app-link hints.