xingbiyun-afk/requirements-docs-viewer

In-App Requirements Document Reader Entry Point (Viewer)

Goal

Integrate existing requirements documents from your project into the product interface, allowing users to read documentation directly on the current page without leaving the application. Simultaneously, ensure the entry point does not slow down initial page load, does not leak historical content, and does not accidentally expose internal documents in production.

Boundary with Document Authoring

• This skill is responsible only for implementing the reading entry point: entry location, document mapping, build-time copying, rendering, search, lazy loading, error states, production exposure surfaces, testing, and walkthrough.
• Document content is provided by prd-rule-authoring or any other source; this skill does not dictate how documents must be written, nor does it require the project to use prd-rule-authoring.
• The two are independent: projects without a reading entry should still produce requirements documents; having a reading entry does not change document writing rules.
• The only coupling point is the document directory + Markdown conventions: paths, titles, renderable syntax. These conventions are defined in the project configuration, not hardcoded in the skill.

When to Use

• Product/development/QA teams want to "see rules directly on the current page" to avoid split-screen MD lookup.
• You already have a well-organized set of Markdown requirements documents that need read-only display.
• You need to integrate internal documents into a delivery demo but must control production visibility.

Not applicable for: online editing/collaboration comments, document approval workflows, full-text search as a service, or role-based granular reading (these can be extended later but are not in the minimal implementation).

Reading Order

File	When to Read
references/integration-design.md	When designing entry point, build, mapping, lazy loading
references/rendering-and-search.md	When handling restricted Markdown rendering, historical section filtering, search
references/acceptance-checklist.md	When testing, walkthrough, and acceptance
references/ops-and-governance.md	When handling production exposure, document updates, and release processes

Minimal Implementation Checklist

1. Entry Point: Display only on pages that have a document mapping; do not render on unmapped pages (no dead buttons); the entry point itself loads zero document content.
2. Source: Document source is Markdown (or equivalent static files) within the repository; copy to the output directory at build time; perform bidirectional validation between output files and mapping at build time (missing or orphaned files cause build failure).
3. Mapping: A registry of route/page → document path is the single source of truth for mapping; organize the document tree by module; identify module-level documents separately.
4. Loading: Request documents only after the drawer/panel is opened; on first open, load the current document; build the search index lazily after opening; do not preload documents on startup.
5. Rendering: Restricted Markdown rendering (headings, paragraphs, lists, tables, code, blockquotes, horizontal rules, links); escape all HTML, output only a whitelist of tags; URL-encode Chinese/bracket file names; adapt to sub-path deployment; sanitize header anchor slugs against HTML/URL dangerous characters (<>&"'), using a single anchor generation function (shared by table of contents, body, search, and navigation).
6. Reader Rules: Show only the latest description — do not render "Update History / Changelog" sections (including their content); exclude them from the table of contents and search as well; if the source document includes historical snapshot annotations, filter them according to project conventions or have the document author omit them.
7. Interaction: Click on table of contents to navigate, action pages can suggest default positioning per chapter, global keyword search (grouped by document, top hit on current page, fragment stripped of Markdown noise) and jump, error states and retry, close. Search result navigation context: clicking a hit should only switch the body content, not clear the search query or result list; preserve the scroll position of the result area; highlight matched items (stable key, at least including document + anchor + title, add fragment to distinguish multiple hits in the same chapter if needed); provide a clear "Clear search" entry to restore the document tree; clear search when opening a document from the tree; do not rebuild the index. Red line: If the table of contents sticks to the top or has an expanded list permanently above the body, click navigation must offset by the covering height to prevent occlusion; use occlusion-level assertions in automation (toBeVisible does not check occlusion). For details on sticky collapsed table of contents, scroll compensation, and other advanced forms, see references/integration-design.md §7.
8. Production Exposure: The entry switch controls only the button, not the static document files; production must choose one of two: exclude the document directory at build time, or add authentication to document paths (implement production access control).
9. Testing: Mapping integrity, build output consistency, historical sections not displayed, lazy loading with zero preload, search and jump, search result context preservation (keyword/results/scroll position retained, successive hits, clearing restores tree, highlighting is unique, no index rebuild), error states; table of contents/navigation with occlusion-level assertions (toBeVisible does not check occlusion); scroll recovery assertions tolerant to clamping (do not require pixel-perfect equality); visible browser walkthrough and archive evidence (screenshots consistent with final behavior).

Boundaries

• Do not modify business page behavior, menu/route business values, or Mock data; only add the reading entry point and document asset pipeline.
• Do not introduce third-party heavy Markdown rendering dependencies; renderer must be restricted, testable, and escapable.
• Do not embed "document writing conventions" in this skill; do not embed "entry point implementation details" in the document writing skill.
• Real permissions, production deployment, and authentication methods are governed by the project's access control; Mock/demo passing does not equal production protection.

Delivery Description

Entry point location and visibility conditions, document source and mapping, build-time copying and validation, rendering and historical filtering, lazy loading and search, error states, production exposure surface handling, testing and walkthrough evidence, uncovered items.