# Documentation reader specification
Status: implemented for the finalized Documentation stage of October 12, 2026. Pair: [user guide](../user/documentation/reader.md).
## Purpose and ownership
The Documentation capability presents literal files in a portable documentation folder. The reader supplies navigation, path validation and rendering. Content, document pairs and domain grouping are not stored in database tables. It does not depend on Accounting or MeOS core.
Files: public/documentation.php, public/documentation.css, public/documentation.js, public/documentation-marked.js; private/modules/documentation/reader.php and marked-LICENSE.md; documentation/manifest.json and its indexed files. Existing public/platform.css supplies the application styling. The Markdown parser is bundled locally (Marked 17.0.5, MIT), not loaded from a network service.
## Installation and shell
documentation/ is alongside private/ and public/, outside the web document root. The existing application_tools table registers documentation_reader in the Documentation menu area, entry documentation.php. application_schema_updates records installation stage documentation_reader_stage_20261012. These are existing shell tables; no table structure changes or documentation-content tables are introduced.
The reader has no database connection or bootstrap dependency. Its Main menu link returns to the existing shell. Existing navigation, accounting pages and actions are not edited. Per-page document links are not installed in this stage; the menu entry gives access to the document index.
## Manifest contract
JSON format_version is 1. stage is a human-readable finalized-stage label. features is an ordered array of {id,title,domain,user,technical}; either audience path can be absent. documents maps each allowed relative path to {title,audience}. Stable feature IDs identify areas independently of PHP filenames. Ordering of feature entries determines domain and item display order.
Paths must lie beneath user/ or technical/ matching their audience, resolve to an existing ordinary file within documentation/, and have extension md, json, sql or txt. The module filters unavailable files and removes empty feature pairs. Unindexed files are not web-readable through this module.
## Reader route and functions
GET documentation.php defaults to the first feature's user guide, or its available technical document. Query feature selects a known ID and audience selects user or technical. Alternatively document selects an exact allowlisted relative path for cross-references. Inputs must be strings; unknown/unavailable values return HTTP 404 with a generic message. Installation/index/read failures return 500 without exposing server paths.
documentation_root resolves the application-root documentation folder. documentation_file rejects absolute/backslash/traversal paths and symlinks resolving outside that root. documentation_catalog validates the manifest, resolves available documents and pairs, and never returns private server paths to the browser. documentation_selection reads the selected indexed document. documentation_escape provides safe HTML output.
Content is provided as escaped plain text first, so it remains readable without JavaScript. The selected document and available link metadata are embedded as JSON using PHP's HTML-safe encoding flags. Only the selected document's content is sent, not the entire technical set.
## Rendering and links
Browser Markdown rendering uses Marked with raw HTML escaped, images reduced to text, links restricted to safe protocols and allowlisted local references. Relative links resolve against the current document and become documentation.php?document=... routes. Missing or omitted local targets remain plain labels. HTTP(S) external links receive noopener/noreferrer. Unsafe protocols and control characters do not create links. JSON/SQL/TXT display as text in a pre element.
The first Markdown H1 is omitted from the rendered article because the reader already provides the document title. Heading IDs allow fragment links. Parser/render failures preserve the escaped fallback; they must not blank the guide or execute embedded markup.
## Navigation behaviour
Root areas are native details/summary elements, initially open, with an expanded/collapsed chevron. Each feature link is indented under its area. Browser sessionStorage remembers collapsed domain names within the tab session; storage failures fall back to expanded roots. No database/preferences changes occur. Keyboard activation uses native summary/link behaviour.
User guide and Developer / AI specification are normal links with current-audience highlighting, not in-place document editing. The selected feature is highlighted. Reference documents may have no paired tabs when they are not a main feature guide. Layout stacks navigation above content on narrow displays.
## Availability and distribution
This installation includes both sets with no visibility toggle. A user-only distribution omits technical/ and technical manifest entries. The runtime also checks file availability, so missing technical files never produce a technical tab. Direct requests for unavailable/unindexed files return 404.
This module does not invent an authentication system. The current installation intentionally serves both sets to visitors who can access its reader. Keeping files outside the public root prevents unrestricted static requests; the reader permits the indexed installed documents. Technical files must actually be omitted from a public user distribution, not merely have their tab hidden.
## Stage finalization
Implementation can change repeatedly during an active stage without minting a release at each step. At finalization, update affected guides/specifications, inspect actual source/schema, verify cross-references and acceptance behaviour, and record deferred work. A stage record identifies what was finalized and validated. Unchanged document pairs need no artificial version increment. This delivery does not assign a new overall MeOS version number.
## Verification scenarios
No database needed to read. Known pair/audience loads. All roots initially open; collapsing one leaves others and selected content intact; navigation retains that choice. Invalid feature/audience/document and traversal are rejected. Symlink outside root rejected. Technical files omitted: no tab/content/direct route. Raw HTML, script and unsafe links are inert. Relative links work, SQL/JSON references readable, source metadata does not expose configuration/session data. Existing action files/core untouched.
No in-app editor, document-content database, automatic publishing system, account/role manager or feature-page links are part of this stage.