# Fliplet Documentation Hub

## Purpose & users
A public documentation site for Fliplet builders, developers, administrators and support readers. Readers browse articles, collections, reusable external resources, search, changelog and previews. Maintenance occurs through an external MCP, outside this app.

## Scope
Core sources: Menu, Collections, Pages, Versions and now Resources for reusable external destinations. Retain Redirects, Changelog, Assets and SearchChunks as supporting sources. Preserve existing documents, routes, public navigation, links and history. Groups was deleted by the owner; home Browse still uses interim static topics. Legacy PageVersions and Navigation remain archived until external consumers are checked. The manager UI was removed. No new auth, translation, semantic search or SSR/SEO work. Do not delete legacy columns/sources before backups and consumers are verified. A project asset `llms.txt` is exposed through an HTML reader route at `/llms.txt`; this does not make the host return a raw `text/plain` response.

## Tech stack
Existing Vue 3 runtime compiler and Vue Router 4, Fliplet Router/Data Sources/Analytics, Lucide, Marked, highlight.js, DOMPurify and short-ID utilities. A guarded boot-time Fliplet.WebMCP shim registers read-only browser-agent tools when document.modelContext is available; it does not replace the external editorial MCP.

## Architecture
The deployed public shell uses Menu/Collections for sidebar navigation. Published Pages supply stable identity, route, status and publishedVersionId; shared publishedContent resolves the current published Version by exact pageId/versionId and supplies article title, summary and Markdown. Article, Home, Search and Changelog article links never fall back to Pages body. Search resolves published Pages to published Versions before ranking. Root-query `?article=<route>` and `?collection=<collectionId>` navigate inside the existing home route for refresh safety. Existing static guide and legacy deep paths remain in the manifest. Changelog is curated separately.

Resources have a unique stable resourceId and label, HTTPS URL and optional description. The new resource reader returns only unique, valid absolute HTTPS links without credentials. A Collection child of targetType Resource resolves by resourceId at read time; descriptions and URLs are never copied into children. The same resource may occur in several collections; absent/unsafe targets render as unavailable rather than breaking the collection. Collection landing is generated from ordered children. Sidebar and both full/instant search show direct external links; search matches resource labels/descriptions, does not crawl external sites or copy their text to SearchChunks. External links opening new tabs announce that behavior and set noopener/noreferrer. Sidebar collection rows retain whole-row expand/collapse with a separate expanded-list view link.

The public Versions rule requires an exact pageId/versionId pair and only the current published pointer. Historical/draft previews need a separate access model, not a wider anonymous rule. Draft saves must not move the published pointer. Public routes remain unchanged, including a protected foundation probe; query-string collection URLs are not separate manifest entries.

The browser-agent WebMCP tools are defined once in the boot HTML after the shared foundation loads and before Vue mounts. The shim registers against document.modelContext when permitted and remains inert otherwise. search_docs, get_doc, list_sections and open_doc read Pages/Versions by source name, matching only current published pointers; open_doc uses the existing Vue router. Tool results whitelist fields, scrub text and limit lengths. Browser permissions policy may prevent discovery or execution even if document.modelContext exists, so runtime tool registration requires an enabled, permitted browser context and separate verification.

Menu contains visible ordered top-level placements. Collections contains `kind=container` rows and archived whole-site snapshots; only containers are navigational. The manager footer, login/manage/account screens and in-app editing were removed. The external MCP must add Resource targeting to its own child editor and enforce required fields, immutable resourceId and HTTPS on writes; the app cannot certify those external controls. Resources has a unique-ID index, public read of its four non-sensitive fields and existing editorial token-only writes. Client readers reject invalid links; the platform's documented hooks do not prove server-side immutability/URL validation for token bulk writes.

Assets support exact-assetId public metadata lookup without page/version ownership filtering. The shared renderer resolves explicit Markdown asset IDs while existing media URLs remain. Legacy records and duplicate historical rows remain. External MCP writer/cycle guard/publication and upload behavior remain unverified. The `/llms.txt` Vue reader fetches the existing text asset at runtime and shows it in a preformatted pane; a screen route cannot change the HTTP content type to `text/plain`.

## Screens
| Screen | Route | Purpose and data |
|---|---|---|
| Documentation home | `/` | Interim static Browse topics, published-Version cards, Changelog; Menu/Collections shell |
| Collection landing | `/?collection=<id>` | Ordered Collection/Page/Resource child list; Menu, Collections, Pages, Resources |
| Article | `/?article=<route>` and existing paths | Published Page identity/current Version content; Redirects, Assets |
| Search | `/search` | Published Pages/current Versions plus direct Resource matches, full and instant search |
| Changelog | `/changelog` | Curated updates and Version-resolved links |
| Exact preview | `/version-preview?pageId=…&versionId=…` | Historical/draft preview surface; access compatibility pending |
| llms.txt reader | `/llms.txt` | Displays the existing llms.txt project asset verbatim in an HTML screen; not a raw text endpoint |
| Not found / redirect | Catch-all and `/not-found` | Safe recovery |

Preserve existing static-guide paths, eight security article route entries and public links. Former management URLs show Page not found.

## Code organization
- `src/App.js` mounts public shell and registers shared components/utilities, including `publishedContent` and `resources`.
- `src/styles/theme.css` holds shared theme and article rhythm.
- `src/components/` holds DocWorkbenchShell, SidebarNav, UniversalSearchOverlay, TOCs and MarkdownRenderer.
- `src/screens/` holds Home collection landing, Article, Search, previews and the llms.txt reader.
- `src/assets/llms.txt` is the project's source text for the reader screen.
- `src/utils/` holds documentationData.js, search.js, markdown.js, publishedContent.js and resources.js.
Keep Vue SFC format, purpose headers and namespaced CSS; edit screens surgically. External MCP code is not in this app. Browser WebMCP shim/tool definitions live in the preview screen's boot HTML, not in the external MCP.

## Design language
Evidence-led technical workbench: existing white/dark-system paper, muted panels, near-black/white ink, restrained plum #7e4c79, Poppins headings, Inter reading text and monospace code. Responsive desktop sidebar/read column/right TOC and mobile drawer; readable media/code/tables and thumb-friendly links. External resource rows reuse existing list and card treatments without changing the palette.

## Data sources
| Source | Meaning and present access |
|---|---|
| Menu | menuId, label, order, visible, targetType, targetId; public visible=true reads; token writer. |
| Collections | Container collectionId,label,ordered children JSON referencing Collection/Page/Resource (Resource has no versionId); snapshot rows retained; public container reads; token writer. |
| Resources | Four columns only: unique resourceId, label, url, description. Public read, token-only writes. Current example `res_fliplet_github` appears in Guides and Developer Docs & APIs; required/immutable/HTTPS server validation for external writes remains outside this app. |
| Pages | Published identity/pointers plus transitional legacy body fields; current public reader uses Versions. |
| Versions | Retained history; public exact-pair reads restricted to current published Page pointer; manager/token access unchanged. |
| PageVersions | Archived transitional revisions and unresolved conflicts, not public. |
| Groups | Deleted by owner; no production app reads. |
| Navigation | Archived snapshot placements; external client status unknown. |
| Assets | Shared IDs/file URLs; optional legacy ownership fields; exact assetId public metadata read. |
| Redirects, Changelog, SearchChunks | Retained existing records/rules; public search reads current published Versions and Resources directly. |
| Documentation Managers | Historical login pool retained; in-app management removed. |

## Decisions log
- 2026-09-10 — Adopted the supplied five-source schema without adding an editorial source because it separated live pages, history, hierarchy, redirects, and changelog.
- 2026-09-10 — Chose Vue 3 with Vue Router for the multi-screen reactive documentation experience.
- 2026-09-10 — Kept the first release public and read-only; authentication and authoring were deferred.
- 2026-09-10 — Made the mock fixture match Data Source columns exactly.
- 2026-09-10 — Preserved the prototype's evidence-led workbench and responsive documentation patterns.
- 2026-09-10 — Used Vue SFC screens and shared components for the V3 runtime.
- 2026-09-10 — Replaced nested named-slot composition with a shared shell due to runtime SFC parsing constraints.
- 2026-09-10 — Required published-status filters on public Pages and Changelog queries.
- 2026-09-10 — Kept PageVersions non-public to protect drafts and history.
- 2026-09-10 — Upgraded deterministic search with URL-synced filters and chunked rendering.
- 2026-09-24 — Replaced the Markdown parser with Marked, highlight.js, and DOMPurify.
- 2026-09-24 — Moved the documentation shell into App.js so sidebar navigation stays mounted.
- 2026-09-29 — Consolidated universal and full search on one utility.
- 2026-09-29 — Reworked mobile navigation into a compact masthead and persistent drawer.
- 2026-09-29 — Switched appearance to browser/device prefers-color-scheme.
- 2026-09-29 — Added GitHub-compatible Markdown alerts and the living formatting guide.
- 2026-09-29 — Migrated page/version relationships to immutable prefixed Base58 identifiers.
- 2026-09-29 — Added closed-pool email-OTP manager access and manager-only writes.
- 2026-09-29 — Centralized legacy authoring writes and diagnostics in docsAdmin.js.
- 2026-09-29 — Added protected hierarchy editing and stable internal page-ID links.
- 2026-09-30 — Added reading progress, copyable section links, and unlisted exact-version previews.
- 2026-09-30 — Adopted the document-oriented target data model while preserving the existing app and legacy consumers; no UI or routing changes were made during migration.
- 2026-09-30 — Kept legacy sources and Pages legacy fields transitional because current editor, renderer, navigation, search, and preview consumers have not yet been migrated.
- 2026-09-30 — Reconciled against the supplied backup as the authority. The backup records 16 published Pages and 19 PageVersions, of which 13 have no publishedAt value.
- 2026-09-30 — Restored nine damaged Version rows and rebuilt SearchChunks as 69 heading-based sections covering all 28 non-empty Versions under migration_backup_reconcile_20260930_v3.
- 2026-09-30 — Cleared the unverified folder ID on asset file 8709465; size and checksum remain empty because available metadata cannot prove them.
- 2026-09-30 — Replaced per-article manifest registration with a final dynamic Article catch-all. Fixed app routes retain priority; new published documentation URLs now resolve from Pages.route without manifest updates.
- 2026-09-30 — Consolidated documentation theme spacing/border/type tokens and shared Markdown presentation; extracted repeated desktop contents markup to DesktopToc while preserving the public catch-all and manager access.
- 2026-09-30 — Switched newly generated version-preview links to a query-based route because the old preview path collided with Studio's preview base; left ordinary article paths and older links intact.
- 2026-09-30 — Kept the historical preview data access rule unchanged: a URL fix must not silently widen public access to legacy revisions.
- 2026-09-30 — Added concrete public manifest routes for eight published security articles before the catch-all after a reader demonstrated published-host refresh failed; preserve legacy links, verify all eight render in preview, and require a separate post-publication host check. This qualifies the earlier catch-all-only decision for published deep links.
- 2026-10-05 — Adopted Menu, Collections, Pages, and Versions as the four core reader sources; the duplicate hierarchy/history sources are transitional only.
- 2026-10-05 — Removed in-app manager sign-in and authoring because the owner's external MCP manages content; do not delete legacy sources until that consumer and all readers are migrated.
- 2026-10-05 — Made publishedVersionId the sole default article-content pointer and restricted public history reads to exact page/version pairs; draft saves cannot change reader output.
- 2026-10-05 — Chose root-query article and collection URLs to preserve refresh-safe published links without relying on nested host rewrites.
- 2026-10-05 — Collections contain only ordered references; their landing views are generated from children, and a page/collection can be reused without content copies.
- 2026-10-05 — Require fresh private backup and hash/conflict report before migration writes; conflicting content blocks cutover rather than being overwritten.
- 2026-10-05 — Owner chose to archive nine divergent PageVersions copies and migrate only unconflicted history; no conflicting bodies will be overwritten or renumbered.
- 2026-10-05 — Seeded seven new Collections containers and seven ordered Menu placements from published snapshot and Groups; 32 whole-site snapshot records remain in place.
- 2026-10-05 — Used a tightly scoped public Menu script requiring an exact boolean-visible predicate after declarative boolean validation caused a runtime read error; no public writes or list-all reads were added.
- 2026-10-05 — Bound the existing Collections manager rule to its manager login source when adding a public container read rule, closing an unbound-role warning without changing the token writer.
- 2026-10-05 — Owner opted to update the site's shared-asset resolution now and defer external MCP adapter changes; do not claim checksum-based upload reuse or new-version deduplication before adapter code is supplied and tested.
- 2026-10-05 — Added exact assetId public metadata lookup rather than anonymous list-all; linked media are validated by host and fileId before display, and existing Markdown URLs/historical Assets records are preserved.
- 2026-10-05 — Added a non-unique checksum index to support future upload matching without imposing false uniqueness on legacy duplicate rows; no missing hashes were invented.
- 2026-10-05 — At the owner's request, removed the manager link and three in-app management screens before remaining reader cutover; retained all records and manager data. Protected probe redirects to public home.
- 2026-10-05 — Owner deleted empty Groups before reader cutover. Removed remaining production Groups reads; home Browse uses four static Search links, without fabricated article bodies.
- 2026-10-06 — Owner narrowed public reader cutover to CURRENT published Versions only. Shared exact-pointer resolution in Article/Home/Changelog/Search and restricted public Versions reads; deferred historical preview access and legacy-column deletion pending MCP verification.
- 2026-10-07 — Added Resources as shared external destinations with four fields, unique stable ID, public read/token-only writes; resource references live in Collections children, not copied content. Guides and Developer Docs & APIs reuse one example. Portal readers reject unsafe URLs; required/immutable/HTTPS validation on external MCP writes is still unverified and must not be claimed. Preserved whole-row collection expansion and existing design.
- 2026-10-14 — Added guarded read-only browser WebMCP tools in the boot HTML for current published documentation only, retaining existing UI and the separate editorial MCP. Browser permissions policy still governs actual agent access.
- 2026-10-23 — Registered a public `/llms.txt` route that reads the existing project text file into an HTML viewer at the owner's request. This path is not a raw plain-text HTTP endpoint; publishing and hosted refresh remain separate checks.

## Known gaps
- The owner attests to a fresh off-app private export of prior sources, but the AI cannot inspect or hash it; historical counts are not proof of backup completeness.
- Nine legacy same-ID versions differ in Markdown; two additional same-ID sourceRef values disagree with Versions metadata. They remain archived per owner decision.
- Historical/draft exact-version previews cannot read older Versions under current anonymous rule. Design distinct authenticated/token preview mechanism rather than broadening public access.
- Eight security article routes exist, but published Pages rows/rendering and host refresh must be independently checked before claiming live availability.
- External MCP source is outside app; Resource child editing/selection, URL and required-field validation, immutable ID enforcement, writer cycle guard/publication and asset deduplication are NOT verified. ResourceId uniqueness is indexed, and unsafe URLs are filtered in public readers; this does not validate external writes. The MCP must reject Resource child versionId and missing/unsafe target before saving.
- Existing asset metadata may lack checksum/size and have historical duplicate rows; preserve IDs/URLs.
- Public reads checked in Studio preview, not anonymously on published host; host refresh/publication needs separate verification. `/llms.txt` remains an HTML response even if its reader route is published; actual text/plain at the host root needs hosting-level support.
- The Studio preview exposes document.modelContext but rejects getTools() with a permissions-policy NotAllowedError; Chrome flag-enabled agent discovery, executeTool and DevTools Application registration remain unverified in a permitted browser.
- Two historical parent references remain unresolved; preserve them rather than fabricating data.
- Whole-site Collection snapshots remain archived, not reinterpreted as containers.
- This feature did not remove existing data or resolve the prior phased migration's pending preview/external-consumer gaps.