> For the complete documentation index, see [llms.txt](https://klassdocs.gitbook.io/klassapp-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://klassdocs.gitbook.io/klassapp-documentation/docs/evidence/staging-docs-serve-gap/root-cause.md).

# Staging Docsify serve gap — root cause (investigation only)

Date: 2026-09-17\
URL under test: the staging `/docs/community/#/./` page (host: see the private repo KlassApp-Foundation/internal or the Cloud dashboard)

## How staging actually serves docs

Not as a static tree under `public/docs/`. A **single Laravel route** in `routes/web.php`:

```php
Route::get('/docs/community/{path?}', function ($path = '') {
    $base = base_path('docs/community');
    // …serve file from docs/community only, or SPA-fallback index.html
})->where('path', '.*');
```

| Path                                               | Staging result                           |
| -------------------------------------------------- | ---------------------------------------- |
| `/docs/community/`                                 | 200 `text/html` (index.html)             |
| `/docs/community/README.md`                        | 200 `text/markdown`                      |
| `/docs/community/_sidebar.md`                      | 200 `text/markdown`                      |
| `/docs/shared/docsify-klassapp.css`                | **404** Laravel error page (`text/html`) |
| `/docs/` / `/docs/index.html` / `/docs/roadmap.md` | **404**                                  |

Local verification used `python3 -m http.server` with cwd=`docs/`, so `../shared/docsify-klassapp.css` resolved and returned CSS. That path **does not exist** on the Laravel-served surface.

## Browser evidence (Playwright)

* Theme link href: `../shared/docsify-klassapp.css`
* Resolved absolute URL: the staging `/docs/shared/docsify-klassapp.css` path (host: see the private repo KlassApp-Foundation/internal or the Cloud dashboard)
* Network: **404**, `Content-Type: text/html` (app 404 page, not CSS)
* Console: `Failed to load resource: the server responded with a status of 404 ()`
* `requestfailed`: same CSS URL → `net::ERR_ABORTED`
* Docsify **does** load and execute (CDN JS 200; `#app` renders markdown; H1 = “KlassApp Community”)
* Theme tokens absent: `--d-canvas` empty; `body` background `rgb(255, 255, 255)` (default vue.css white), not parchment `#FAFAF5`
* Secondary: jsDelivr pagination CSS hit `net::ERR_BLOCKED_BY_ORB` (MIME/ORB); pagination JS still 200 — secondary to theme break

Screenshots: `01-staging-community-hash-dot.png`, `02-after-roadmap-sidebar-click.png`\
Full dump: `REPORT.json`

## Root cause (one sentence)

**The DESIGN\_SYSTEM Docsify theme lives at `docs/shared/`, but production/staging only expose `docs/community/*` via Laravel; the relative `../shared/` stylesheet URL 404s, so staging runs unthemed Docsify even though markdown content loads.**

Same class of gap: local static server ≠ Laravel route surface.

## Out of scope for this report

Fix options (not implemented here): extend Laravel routes to serve `docs/shared` (and hub `docs/`), or copy/inline the CSS under `docs/community/`, or change the link to a path the existing route can serve.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://klassdocs.gitbook.io/klassapp-documentation/docs/evidence/staging-docs-serve-gap/root-cause.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.