` and plain headings so a
GitHub-README stylesheet (`github-markdown-css` + a highlight.js theme) can
style the page. Full option reference and integration recipes:
**[docs/standalone-renderer.md](docs/standalone-renderer.md)**.

---

## Security

Defense in depth — details and the hardening checklist:
**[docs/security.md](docs/security.md)**.

- **Path validation**: 14 layers (length, NUL, control chars, URL-decode
  re-check, absolute paths, traversal, strict Unicode whitelist `\p{L}\p{M}\p{Pd}`,
  depth, extension, realpath containment, symlink-safe re-check) — one
  validator for viewer, downloads, media, uploads, per-directory ini and admin.
- **Output sanitization**: every rendered document passes a DOM-allowlist
  sanitizer (event handlers, dangerous schemes, forms, foreignObject/``
  all die); author raw HTML is escaped unless `ALLOW_RAW_HTML` is on — and
  sanitized even then.
- **Transport**: strict CSP with per-request nonces, nosniff, frame/r
  eferrer/permissions policies, COOP; hardened session cookies.
- **Admin**: password_hash login, per-IP rate limiting, CSRF on every
  mutation, session regeneration, audit trail, soft deletes, first-run setup
  gated by localhost-or-one-time-code.
- **Secrets**: `.md.ini` is never served (`.htaccess` + outside-docroot
  layouts); machine API answers JSON only.

---

## Development

```bash
composer install                 # dev deps: phpunit, phpstan
cd tools/frontend && npm install && node build.mjs && cd ../..

composer test                    # 126 PHPUnit tests
composer stan                    # PHPStan level 6
php -S localhost:8080 -t public public/router.php
```

The frontend pipeline (Tailwind v4 → `app.css`, esbuild → `app.js`/`admin.js`,
theme compiler → `themes.css`, icon/emoji generators) runs at **development**
time only — built assets are committed, so production servers need no Node.js.
Architecture, module map, release checklist: **[docs/development.md](docs/development.md)**.

### Project layout

```text
MD.Scribe/
├── public/              ← recommended docroot
│   ├── index.php        front controller (viewer, library, pages, JSON API)
│   ├── admin.php        admin panel + admin JSON API
│   ├── router.php       php -S dev router
│   └── assets/          css/ js/ vendor/{mermaid,katex,fonts} img/  (all local)
├── src/                 PSR-4 app code (MdViewer\)
│   ├── Core/            App, Config, FeatureFlags, Request/Response, Session,
│   │                    Csrf, Logger, AuditLog, HttpClient, Paths, Version
│   ├── Http/            FrontController, AdminKernel, Controllers/
│   ├── Markdown/        engine, sanitizer, glossary, mermaid repair, cache,
│   │                    Extensions/ (math, sub/sup, emoji, alerts, renderers)
│   ├── Files/           PathValidator, repository, search index, uploader,
│   │                    FileManager
│   ├── Admin/           auth, backups, updater, health, link checker
│   ├── Theme/           theme catalog (shadcn token model)
│   └── View/            template engine, generated icon sprite
├── templates/           layout/ viewer/ browser/ pages/ admin/
├── config/              defaults.php (schema) · themes.php · manifest.json
├── content/             ← your documents live here (default BROWSE_DIR)
├── storage/             cache/ backups/ logs/ index/ state/ themes/  (writable)
├── docs/                deep documentation
├── tests/               PHPUnit (Unit + Feature)
├── tools/               build pipeline (frontend/, build-manifest.php)
├── deploy/              nginx, Caddy, Docker, php.ini
├── md.php               v2-compatible viewer shim
├── updater.php          v2-compatible updater + machine API shim
└── index.php            project-root entry (docroot-at-root installs)
```

---

## Documentation

| Document | Contents |
| --- | --- |
| [docs/installation.md](docs/installation.md) | All deployment layouts, Apache/nginx/Caddy/Docker, shared hosting, permissions |
| [docs/configuration.md](docs/configuration.md) | Complete `.md.ini` reference, per-directory files, feature toggles |
| [docs/markdown-features.md](docs/markdown-features.md) | Full syntax matrix with examples |
| [docs/admin-guide.md](docs/admin-guide.md) | Every admin page, workflows, machine API |
| [docs/theming.md](docs/theming.md) | Theme system, tokens, custom themes, recipes |
| [docs/security.md](docs/security.md) | Threat model, hardening checklist, CSP notes |
| [docs/http-api.md](docs/http-api.md) | JSON endpoints (public + admin + machine API) |
| [docs/development.md](docs/development.md) | Architecture, build pipeline, testing, releases |
| [docs/troubleshooting.md](docs/troubleshooting.md) | Common problems and fixes |
| [docs/upgrade-from-v2.md](docs/upgrade-from-v2.md) | Migration mapping and steps |

---

## Upgrading from v2

Drop-in: deploy v3 beside your v2 files, move (or point `BROWSE_DIR` at) your
documents, keep the root `md.php` shim — every old bookmark and `?file=` link
works. Step-by-step: **[docs/upgrade-from-v2.md](docs/upgrade-from-v2.md)**.

## License

PolyForm Noncommercial 1.0.0 — see [LICENSE](LICENSE).
Markdown engine: [league/commonmark](https://commonmark.thephpleague.com/) (BSD-3).
Highlighting: [scrivo/highlight.php](https://github.com/scrivo/highlight.php) (BSD-3, highlight.js port).
Diagrams: [Mermaid](https://mermaid.js.org/) (MIT). Math: [KaTeX](https://katex.org/) (MIT).
Icons: [Lucide](https://lucide.dev/) (ISC). Emoji data: [gemoji](https://github.com/github/gemoji) (MIT).
Fonts: Inter & JetBrains Mono (SIL OFL).