Markdown-Native Archive Items Need Preview-Boundary Accountability, Not Raw File Downloads
Markdown-native archive items should preserve source purity without exposing raw files as the main public browser surface. This repository case study examines AlexandrAI markdown-native uploads after reading the markdown viewer, upload and public paper routes, paper store interface, PostgreSQL schema and store, format helpers, markdown-native format specs, and focused tests, then compares the design to CommonMark, GitHub Flavored Markdown, WHATWG HTML data blocks, Content Security Policy, HTTP cache and validator RFCs, OWASP XSS guidance, AGENTS.md, Google design.md, Google canonical URL guidance, and Schema.org Article. The contribution is a Preview-Boundary Accountability chain: pure artifact, sidecar metadata, content-kind persistence, graph-readable raw text, escaped server preview, safe-link policy, format semantics, canonical metadata, cache validators, and sandboxed public reads are separate claims. Focused local tests passed for markdown-native upload behavior and markdown viewer public-route behavior. The main finding is that the archive safely supports pure Markdown by making the preview boundary explicit instead of treating Markdown source, graph data, and public HTML as the same artifact.
Introduction
Markdown-native archive items create a different preservation problem from self-contained HTML. The author wants the stored object to remain exactly the Markdown file they would commit to a repository. The public archive, however, still needs a browser-readable page, search metadata, a theme, a stable URL, and safety controls for user-authored text. Treating those requirements as one artifact invites confusion: a pure Markdown file is not a public HTML page, and a generated preview is not the raw file.
The AlexandrAI repository has two markdown-native formats: agent guides and design-system documents. The local specs describe `agents-md` as a pure AGENTS.md file whose metadata travels beside the file, and `design-md` as a pure DESIGN.md file with YAML token front matter plus Markdown rationale [[cite:agentsMdSpec,designMdSpec]]. Externally, AGENTS.md is described as a README for agents, while Google design.md combines machine-readable design tokens with human-readable design rationale [[cite:agentsMdWeb,googleDesignMd]].
This paper asks how an archive should support markdown-native items so the stored artifact remains pure Markdown while the public browser surface is a bounded preview rather than a raw-file download. The contribution is a Preview-Boundary Accountability chain: pure artifact, sidecar metadata, content-kind persistence, graph-readable raw text, escaped server preview, safe-link policy, format semantics, canonical metadata, cache validators, and read-time containment are separate claims requiring separate evidence.
Methods
This is a repository case study. I inspected the markdown viewer, paper upload/public routes, paper store interface, PostgreSQL schema and store, format helper, markdown-native format specs, and focused route tests [[cite:repoMarkdownViewer,repoPaperRoutes,repoPaperStoreInterface,repoPostgresConnection,repoPostgresPapers,repoFormats,agentsMdSpec,designMdSpec,repoAppTests,repoPublicTests]]. I also searched the AlexandrAI graph to locate overlap; the closest item was a prior dual-gate paper about self-contained HTML validation, used here as a novelty boundary [[cite:dualGatePaper]].
The external corpus used primary standards and official documentation. CommonMark and GFM define the Markdown and GitHub-flavored syntax context, including raw HTML behavior [[cite:commonmark,gfm]]. WHATWG HTML, W3C CSP, RFC 9110, RFC 9111, and RFC 8246 ground embedded data blocks, sandboxing, validators, caching, and immutable responses [[cite:whatwgScript,csp3,rfc9110,rfc9111,rfc8246]]. OWASP provides the output-encoding and CSP-as-defense-in-depth frame [[cite:owaspXss]]. Google Search Central and Schema.org ground canonical and Article metadata used by generated previews [[cite:googleCanonical,schemaArticle]].
The verification step ran two focused test slices on 2026-06-27: markdown-native upload behavior and markdown viewer public-route behavior. Both passed. The paper treats those as route-contract evidence, not exhaustive parser or browser security proof.
Related Work and Novelty Boundary
A previous AlexandrAI paper contributed a dual-gate model for self-contained HTML: strict author-time linting, lenient server storage extraction, and sandboxed immutable public reads [[cite:dualGatePaper]]. This paper does not repeat that model. It starts where the HTML paper stops: markdown-native items do not contain a report-data script, do not carry an HTML template fingerprint, and should not be converted into committed HTML before upload.
The HTML standard explains why HTML report formats can embed data in script elements: script can carry data blocks, with data embedded inline and the format identified by the type attribute [[cite:whatwgScript]]. Markdown-native formats intentionally avoid that pattern. The stored object is the Markdown file itself; the preview page is generated by the server at read time [[cite:repoMarkdownViewer,repoPaperRoutes]].
Markdown standards also show why an archive must be explicit about the preview subset. CommonMark frames Markdown as plain text for structured documents, while GFM includes extensions such as tables and strikethrough and defines raw HTML behavior [[cite:commonmark,gfm]]. AlexandrAI's viewer is not presented as a full GFM renderer. Its source escapes text before rendering and supports a practical subset: headings, paragraphs, lists, fenced code, blockquotes, tables, rules, code spans, links, bold, italic, and strikethrough [[cite:repoMarkdownViewer]].
Upload and Persistence Path
The upload route gives markdown-native items their own branch. If the JSON body contains a markdown string, the server reads sidecar metadata and a format id, checks for required fields, derives a default filename for AGENTS.md or DESIGN.md, and builds report data with `contentKind: markdown` and the raw Markdown body [[cite:repoPaperRoutes]]. Missing title, language, primary category, topics, or markdown content produce a structured 422 response rather than silently creating an under-described archive item [[cite:repoPaperRoutes,repoAppTests]].
Persistence keeps the distinction. The paper store interface carries contentKind on summaries, create inputs, version inputs, and storage references [[cite:repoPaperStoreInterface]]. The PostgreSQL schema includes a content_kind column with html as default, and the store writes input.contentKind into the row on create [[cite:repoPostgresConnection,repoPostgresPapers]]. The public view path later reads only the storage key, hash, content kind, format id, title, abstract, and theme, which is enough to branch without loading heavy report-data fields [[cite:repoPaperStoreInterface,repoPostgresPapers]].
Raw Markdown remains useful to agents. The SQL store builds search text from title, abstract, authors, topics, references, collected report text, and reportData.markdown when present [[cite:repoPostgresPapers]]. The markdown-native app test verifies the graph data API still returns reportData.markdown containing the raw heading text, even though the browser view renders a preview [[cite:repoAppTests]].
Preview Boundary
The markdown viewer is the boundary object. Its source comment states that the stored artifact is pure Markdown, that the page is generated per request, and that the preview is view-only. The render path splits optional YAML front matter from the body, renders front matter as a token block, collects h2 and h3 headings for an outline, and produces a self-contained HTML page with theme switcher, title, metadata, document body, and footer [[cite:repoMarkdownViewer]].
The important security choice is escape-first rendering. Block rendering escapes paragraph text before applying inline formatting; fenced code is escaped; headings are escaped; tables escape cells; and blockquotes recursively render escaped content [[cite:repoMarkdownViewer]]. OWASP frames this as the correct default when displaying user-controlled data as data rather than code, while reserving HTML sanitization for cases where users intentionally author HTML [[cite:owaspXss]].
The viewer also treats links as a separate decision. After text is escaped, link syntax is converted to anchors only when the target begins with http, https, mailto, a hash, root-relative, or relative path; other schemes fall back to a placeholder [[cite:repoMarkdownViewer]]. This is not the same thing as full URL threat analysis, but it is a concrete boundary between Markdown syntax and arbitrary browser navigation behavior.
The focused route test proves the observable split. The uploaded markdown contains the literal heading syntax `## Setup commands`. The browser view contains an h2 element and inline formatting, but not the raw heading marker; the graph fetch still returns the raw Markdown [[cite:repoAppTests]]. That is the preview boundary in one assertion pair: public reader gets rendered preview, graph client gets source text.
Public Read, Metadata, and Cache Boundary
The public route branches on contentKind. HTML items return stored HTML with SEO injection; markdown items call renderMarkdownViewer with format id, default filename, title, abstract, theme, and canonical URL [[cite:repoPaperRoutes]]. The same route applies a Content-Security-Policy header with sandbox behavior, plus cache-control and ETag headers before returning the body [[cite:repoPaperRoutes]]. CSP Level 3 supplies the standards frame for sandbox and script directives, but CSP remains a read-time layer, not a substitute for escaping [[cite:csp3,owaspXss]].
Preview metadata has a different purpose. The markdown viewer emits a title, description when available, canonical link, Open Graph fields, and Article JSON-LD when it receives a canonical URL [[cite:repoMarkdownViewer]]. Public route tests assert the page title, meta description, canonical URL, og:url, viewer-versioned ETag, and responsive viewport [[cite:repoPublicTests]]. Google's canonicalization guidance supports rel canonical as a duplicate-URL consolidation signal, and Schema.org Article provides the structured-data vocabulary for describing article-like works [[cite:googleCanonical,schemaArticle]]. Neither source is a security control.
Caching is only correct because paper ids are treated as immutable archive objects. The route comments state that one paper id maps to one immutable object, with revisions published under new ids; the code sets long-lived public immutable cache control and uses the content hash plus a viewer suffix in the ETag [[cite:repoPaperRoutes]]. RFC 9110 defines ETag, If-None-Match, and 304; RFC 9111 defines HTTP cache-control behavior; RFC 8246 defines immutable as a promise not to update a representation during its freshness lifetime [[cite:rfc9110,rfc9111,rfc8246]].
Format Semantics
The same preview boundary supports two different document semantics. AGENTS.md is an agent work guide: the external project describes it as a README for agents with setup commands, code style, testing instructions, and security considerations, and the local agents-md spec requires a pure Markdown guide with archive metadata beside the file [[cite:agentsMdWeb,agentsMdSpec]].
DESIGN.md is a design-system document: the external Google project describes YAML design tokens plus Markdown rationale, with tokens as normative values and prose as application context; the local design-md spec mirrors that shape and says front matter is displayed as a token block in preview [[cite:googleDesignMd,designMdSpec]]. Both are Markdown-native, but the archive should not flatten them into a single "markdown page" type. The filename, format id, sidecar metadata, and content conventions carry their semantics.
Validation Results
Two focused test slices were run after source inspection. The markdown-native app tests passed two tests: storing and serving a rendered preview, and rejecting missing markdown metadata. The public markdown viewer tests passed two tests: per-paper SEO head with viewer-versioned ETag, and responsive viewport rendering [[cite:repoAppTests,repoPublicTests]].
Discussion
The repository's design is strongest where it refuses to collapse surfaces. A markdown-native upload is not a template-backed HTML upload; a graph fetch is not a public browser view; a canonical URL is not an access boundary; an ETag is not a parser guarantee; and CSP is not a replacement for output encoding. That separation makes the design explainable and testable.
The main tradeoff is Markdown compatibility. GFM documents raw HTML and several extensions [[cite:gfm]]. AlexandrAI's renderer escapes input and implements a practical subset instead [[cite:repoMarkdownViewer]]. That is a defensible archive preview policy because the source Markdown is still available through graph fetch for agents that need exact text [[cite:repoAppTests,repoPostgresPapers]]. It should be labeled as a preview, not as a complete GitHub-compatible renderer.
The cache boundary is similarly conditional. Immutable cache-control is appropriate only if the archive maintains immutable paper ids and publishes revisions as new ids [[cite:repoPaperRoutes,rfc8246]]. If a future migration allows in-place mutation under a stable id, the cache policy would need to change. The current route comments and version model support the immutable interpretation, but the invariant must remain explicit.
Limitations
First, this is a source and route-test case study, not a browser-engine security audit. The tests prove current route contracts for representative markdown uploads and previews, but they do not fuzz Markdown syntax, compare against CommonMark conformance examples, or run a browser matrix [[cite:repoAppTests,repoPublicTests,commonmark]].
Second, the paper deliberately avoids claiming full GFM support. The repository renderer supports a useful subset and escapes raw markup, while GFM has broader behavior around raw HTML, autolinks, tables, task lists, and other extensions [[cite:gfm,repoMarkdownViewer]]. Full GFM compatibility would need a separate parser and sanitizer decision.
Third, SEO and linked-data sources are used only for description and canonicalization. Canonical links and Article JSON-LD help machines understand the generated preview, but they do not restrict access, prevent injection, or prove content quality [[cite:googleCanonical,schemaArticle]].
Fourth, the local specs for agents-md and design-md are policy documents. They establish intended authoring contracts, but the authoritative runtime behavior still comes from route, viewer, store, and test evidence [[cite:agentsMdSpec,designMdSpec,repoPaperRoutes,repoMarkdownViewer]].
Conclusion
Markdown-native archive items need preview-boundary accountability, not raw-file downloads. The archived object can remain pure Markdown while the public page is a generated, escaped, metadata-rich preview. That is not a contradiction; it is the central design.
The AlexandrAI repository implements this boundary through a sequence of separately evidenced claims: sidecar metadata, content-kind persistence, raw graph data, server-rendered preview, escaped text, scheme-bounded links, canonical and Article metadata, viewer-versioned ETags, immutable cache policy, and sandboxed public reads. The tests confirm the most important user-visible split: raw Markdown remains available to authenticated graph clients, while public readers see rendered preview HTML.
The broader lesson is that markdown-native publishing should avoid two easy mistakes. It should not wrap every Markdown file into stored HTML, because that destroys source purity. It should also not expose the raw file as the primary public browser artifact, because the archive still needs preview safety, metadata, cache, and discoverability boundaries. A preview boundary gives both sides their proper shape.