[kylebernhardy]

⊙ Problem

Operators need configuration and interpretation guidance for the optional full-text analytics added by Add opt-in native full-text analytics. The existing full-text overview and release notes also describe the older engine version.

🤔 Is this documentation needed before enabling the feature?

Yes. Exact cumulative counters, unavailable observations and worker-specific series require different interpretation from averaged request metrics. Keep collection opt-in and explain its costs without claiming a production overhead bound.

💡 Solution

Document how to enable collection dynamically, read the fulltext metric, and calculate rates without losing integer precision or crossing reset boundaries. Update the engine guidance to fulltext 0.9.0 while retaining the existing migration limits.

🔧 Changes

Product and architecture tour

Configure, interpret, then upgrade

Start with configuration, then interpret observations and check upgrade requirements:

• Configuration options adds analytics.fullText, a minimal enabled: true example, implied defaults, validated cadence bounds, optional histograms and reader-byte observations. Live configuration notes cover override retirement after environment overlays and the union of recording requests during operator export.
• Analytics overview explains protected retrieval, flat decimal values, latest observations per worker/index/role, rate baselines, unavailable and incomplete coverage, dropped rows, queue overlap, privacy exclusions and collection costs. Internal consumers are implementation hooks, not a public subscription API.
• Full-text search overview links the analytics guide and updates the engine to 0.9.0. Compatible text-only 0.7/0.8 checkpoints require no additional rebuild; older declarations retain their documented rebuild or qualification requirements.
• Query optimization documents 0.9.0 checkpoint compatibility and storage.fullText.query capacity settings: maxQueryTerms defaults to 64 (maximum 1024); maxQueryClauses defaults to 256 (maximum 4096). Changes require a full Harper process restart; restart_service alone does not apply them.
• Harper 5.4 release notes introduces opt-in telemetry and aligns the engine and compatible-checkpoint statements with the reference pages.

✅ Verification

• npm run build passed and generated 426 documents for the final wording.
• npm run format:write and npm run format:check passed.
• This docs PR documents runtime behavior; its build does not validate production overhead. Earlier full/delta reviews remain historical. The latest paragraph clarification was checked against the reviewed core behavior and built without another outside review.

Docs for: Add opt-in native full-text analytics.

Depends-on: HarperFast/harper#3946

🤔 Coordinate pending reference changes

Document fulltext 0.8 query policy and fuzzy controls overlaps engine/query wording; preserve 0.9 and both features. Assemble the v5 reference and open release notes from harper and harper-pro moves these pages. If that cutover lands first, port this docs PR into the owning code repository rather than restoring deleted reference files.

Comment generated by kAIle (GPT-6)

Related PRs: #777 overlaps (engine/query guidance), #788 overlaps (reference migration)
Release target: v5.4 — documents the new development-line analytics surface
Complexity: medium

Deferred findings

• b7fa803b170f80d5 nit documentation — reference/configuration/options.md — docs say internal consumers can keep collection active; no core caller exists — filed Implement full-text generation lifecycle, rebuild, eviction, backup, and status harper#2510

_{Review-Coverage: authored=codex; ran=cursor-composer,claude; adjudicated=domain(claude); declined=gemini,cursor-grok,muse; rounds=4; full=2 @ 549b795}

_{Review-Attention: skim ~2m (decisions: doc-the-loss-vs-fix-core, query-knobs-in-this-pr, engine-bump-bundled, dual-fulltext-config-entries) @ 549b795}

[gemini-code-assist]

Code Review

This pull request updates the documentation to introduce opt-in Full-text Analytics for Harper v5.4.0, detailing configuration options, metrics, and fields. It also documents the upgrade of the full-text search engine to @harperfast/fulltext version 0.9.0, explaining checkpoint reuse and new query capacity settings. The review feedback recommends avoiding the <VersionBadge> component mid-sentence in lists, suggesting plain text instead, and restructuring a paragraph in the analytics overview to improve readability and resolve grammatically disjointed phrasing.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-789

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-789

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-789

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-789

This preview will update automatically when you push new commits.

[Ethan-Arrowood]

LGTM !

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.