texlite 0.7.8 → 0.8.1

package/OPERATIONS.md

@@ -0,0 +1,261 @@
+# Operating TexLite
+
+This guide covers installation, configuration, service operation, and backups.
+For the product's intended use and editor comparison, start with the
+[README](README.md). For implementation details and trade-offs, see
+[DESIGN.md](DESIGN.md).
+
+## Requirements
+
+- Node.js 24 or newer and npm
+- `latexmk`
+- At least one configured engine: `pdflatex`, `xelatex`, or `lualatex`
+- `git` only when a project owner uses the optional Git/GitHub integration
+
+Check a host before initialization:
+
+~~~bash
+texlite requirements
+
+# Equivalent individual checks:
+node --version
+npm --version
+latexmk --version
+xelatex --version
+# Optional tools:
+git --version
+texcount -version
+harper-cli --version
+harper-ls --version
+~~~
+
+`texlite init` and `texlite start` validate Node.js, `latexmk`, and every
+engine named in `latex.allowedEngines`. `texlite requirements` can be run
+before initialization: it checks only the default commands on `PATH`, without
+reading a configuration file or any TexLite data. It requires Node.js and
+`latexmk`, and requires at least one of the three supported LaTeX engines.
+`texlite doctor` presents the configured deployment checks and optional host
+tools in a table with their requirement level, installation state, and
+detected version. Missing optional tools never stop the editor:
+Git enables GitHub backup, TeXcount enables document statistics, and
+`harper-cli` enables spelling and grammar diagnostics. `harper-ls` is shown
+for host diagnosis and external editor integrations; TexLite itself invokes
+`harper-cli`.
+
+Formatting does not require a host binary. The browser uses bundled `tex-fmt`
+WASM for `.tex`, `.cls`, and `.sty`, and browser-side `bibtex-tidy` for `.bib`.
+
+### Optional writing checks
+
+TexLite does not bundle Harper. To enable its spelling and grammar diagnostics,
+install a Harper distribution that provides `harper-cli` (the same host package
+normally also provides `harper-ls`) and make it available on the TexLite service
+`PATH`:
+
+~~~bash
+harper-cli --version
+~~~
+
+The command is optional: if it is absent or temporarily fails, TexLite remains
+usable and the browser's native English spellchecker is enabled instead. Native
+browser spellchecking does not provide Harper grammar diagnostics or suggested
+replacements.
+
+## Install and initialize
+
+### Global npm installation
+
+The published package provides the `texlite` executable. Configuration and
+project data are outside the global npm installation:
+
+~~~bash
+npm install --global texlite
+texlite init
+texlite start
+texlite status
+~~~
+
+Open <http://127.0.0.1:3000>. `init` creates the configuration if absent,
+validates the environment, initializes storage, and creates the first
+administrator. The server will not start without an active administrator.
+
+The normal lifecycle commands can be run from any directory:
+
+~~~bash
+texlite stop
+texlite restart
+texlite logs
+~~~
+
+For a clean upgrade, restart after npm has installed the new version:
+
+~~~bash
+npm update --global texlite
+texlite restart
+~~~
+
+Uninstalling the package does not remove configuration or data:
+
+~~~bash
+npm uninstall --global texlite
+~~~
+
+### Source installation
+
+~~~bash
+npm ci
+cp texlite.config.example.json texlite.config.json
+export TEXLITE_CONFIG="$PWD/texlite.config.json"
+# Edit texlite.config.json if needed.
+npm run init
+npm run build
+npm start
+~~~
+
+For non-interactive initialization, supply these environment variables only to
+the initialization command:
+
+~~~bash
+TEXLITE_INIT_USERNAME=admin \
+TEXLITE_INIT_DISPLAY_NAME=Administrator \
+TEXLITE_INIT_PASSWORD='use-a-password-of-at-least-8-characters' \
+npm run init
+~~~
+
+Avoid putting a password into shell history on a shared host.
+
+## Command reference
+
+| Command | Purpose |
+| --- | --- |
+| `texlite init` | Create configuration and the initial administrator. |
+| `texlite serve` | Run in the foreground; suitable for debugging, Docker, or systemd. |
+| `texlite start` / `stop` / `restart` | Manage the bundled-PM2 service. |
+| `texlite status` | Show a colored, systemctl-style status view; add `--json` for scripts. |
+| `texlite logs` | Stream PM2-managed logs. |
+| `texlite requirements` | Check default host commands on `PATH` without loading TexLite configuration or data. |
+| `texlite doctor` | Show configuration/application checks and a table of required and optional host software. Add `--json` for scripts. |
+| `texlite config` | Print effective configuration and paths without changing them. |
+
+`start`, `stop`, `restart`, `status`, and `logs` use the PM2 runtime bundled
+with the global npm package—no separate global PM2 install is necessary.
+Managed startup waits for the HTTP health endpoint, and `restart` recreates the
+managed process so it uses paths from the newly installed npm version.
+
+For a source checkout, `ecosystem.config.cjs` and the `npm run pm2:*` scripts
+remain available. Run exactly one forked instance: cluster mode and multiple
+TexLite processes sharing one data directory are unsupported because
+collaboration state, the compile queue, SQLite, and project files are local to
+one process.
+
+## Configuration
+
+### Where configuration and data live
+
+Configuration path precedence:
+
+1. `--config PATH` passed to `texlite`;
+2. `TEXLITE_CONFIG`;
+3. `$XDG_CONFIG_HOME/texlite/texlite.config.json`;
+4. `~/.config/texlite/texlite.config.json`.
+
+Relative paths are resolved from the configuration file. The default data
+directory is `$XDG_DATA_HOME/texlite`, or `~/.local/share/texlite` when
+`XDG_DATA_HOME` is unset. Set `storage.dataDir` or `TEXLITE_DATA_DIR` to move
+it. The data directory contains the SQLite database, project sources, compiled
+output, history objects, and Git-token encryption key.
+
+Use [texlite.config.example.json](texlite.config.example.json) as a complete
+starting point. It intentionally uses `.texlite` for repository development;
+`texlite init` instead writes the XDG data-directory default.
+
+### Important settings and effective defaults
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| `siteName` | `TexLite` | Site title. |
+| `adminEmail` | empty | Optional administrator contact address. |
+| `server.host` / `server.port` | `127.0.0.1` / `3000` | Keep localhost unless the deployment is separately secured. |
+| `storage.dataDir` | XDG data directory | Stores all persistent project data. |
+| `clientDir` | Installed package's `dist/client` | Normally changed only for development or a custom deployment. |
+| `sessionDays` | `14` | Login-session lifetime. |
+| `uploads.maxFileSizeMB` | `50` MB | Limit for uploads, ZIP entries, and attachments. |
+| `pdf.loadingStrategy` / `pdf.rangeThresholdMB` | `auto` / `5` MB | Chooses full transfer for small PDFs and byte ranges for larger ones. |
+| `history.maxVersions` / `history.maxStorageMB` | `200` / `128` MB | Per-project ordinary-version count and soft storage limit. |
+| `latex.latexmk` | `latexmk` | Host command. |
+| `latex.defaultEngine` | `xelatex` | Must appear in the allowed list. |
+| `latex.allowedEngines` | `pdflatex`, `xelatex`, `lualatex` | Engines available in the UI. |
+| `latex.extraArgs` | `[]` | Additional configured compiler arguments. |
+| `latex.compileTimeoutSeconds` | `600` | Per-job time limit. |
+| `latex.maxCompileJobs` | `10` | Global concurrent LaTeX-process limit. |
+| `latex.allowProjectLatexmkrc` | `true` | Enables an owner-configured, multi-line `latexmkrc`. |
+| `git.binary` / `git.operationTimeoutSeconds` | `git` / `120` seconds | Used only by optional Git integration. |
+| `git.githubApiBaseUrl` | `https://api.github.com` | GitHub REST API endpoint. |
+
+The current environment-variable overrides are:
+
+~~~text
+TEXLITE_CONFIG
+XDG_CONFIG_HOME                 XDG_DATA_HOME
+TEXLITE_SITE_NAME               TEXLITE_ADMIN_EMAIL
+TEXLITE_HOST                    TEXLITE_PORT
+TEXLITE_DATA_DIR                TEXLITE_CLIENT_DIR
+TEXLITE_SESSION_DAYS            TEXLITE_MAX_UPLOAD_SIZE_MB
+TEXLITE_PDF_LOADING_STRATEGY    TEXLITE_PDF_RANGE_THRESHOLD_MB
+TEXLITE_HISTORY_MAX_VERSIONS    TEXLITE_HISTORY_MAX_STORAGE_MB
+TEXLITE_LATEXMK                 TEXLITE_DEFAULT_ENGINE
+TEXLITE_COMPILE_TIMEOUT         TEXLITE_MAX_COMPILE_JOBS
+TEXLITE_GIT                     TEXLITE_GIT_TIMEOUT
+TEXLITE_GITHUB_API_URL
+~~~
+
+Configuration is validated before TexLite opens the database or binds the HTTP
+listener. Invalid JSON types, paths, limits, URLs, engine lists, timeout/queue
+values, and cross-field combinations stop startup with a setting-specific,
+actionable error. Explicit invalid values are never silently replaced with a
+default. `texlite init` applies the same validation.
+
+Accepted limits are: port `1–65535`, sessions `1–3650` days, upload size
+`1–2048` MB, history count `10–5000`, history size `16–102400` MB, PDF range
+threshold `1–2048` MB, compile timeout `1–3600` seconds, compile jobs `1–32`,
+and Git timeout `1–3600` seconds.
+
+Before every compile TexLite passes `-norc` to `latexmk`. A `.latexmkrc` found
+in a ZIP upload, Git checkout, or project file tree is ignored. It is used only
+when the owner explicitly saves it through Project Settings, which passes it
+with `-r`. An `latexmkrc` is executable Perl configuration and should remain
+disabled for users you do not trust.
+
+TexLite never runs `tlmgr` or installs TeX packages. Updating the host TeX
+distribution changes the environment used by subsequent compiles.
+
+## Development and verification
+
+Run the API/server watcher and Vite in separate terminals:
+
+~~~bash
+npm run dev       # API/server: http://127.0.0.1:3000
+npm run dev:web   # Vite UI:    http://127.0.0.1:5173
+~~~
+
+Vite proxies `/api` requests to the server. Validate a production-style build
+with:
+
+~~~bash
+npm run typecheck
+npm test
+npm run build
+npm start
+~~~
+
+## Backup and security
+
+Back up the entire configured data directory, including `texlite.db`, its WAL
+files, `git-token.key`, and `projects/`. Restoring saved GitHub tokens requires
+the same encryption key. For an online copy of SQLite, include WAL files or use
+a SQLite-aware backup method.
+
+TexLite is designed for trusted users on localhost. Shell escape is disabled by
+default and compile jobs have timeouts and concurrency limits, but LaTeX itself
+is not a security boundary. Before exposing it to an untrusted network, add an
+isolated compiler sandbox plus appropriate authentication and network controls.

package/README.md

@@ -1,338 +1,115 @@
-# texLite
+# TexLite
 
-texLite is a lightweight, local-first web workspace for writing, compiling, previewing, and discussing LaTeX documents. It is intended for a small group of trusted users on one server. It uses the LaTeX installation already available on the host instead of shipping a LaTeX container, and keeps the rest of the stack deliberately small.
-
-**Documentation:** English (this file) · [Design](DESIGN.md) · [简体中文](README.zh-CN.md)
-
-**Website:** [TexLite GitHub Pages](https://swufe-db-group.github.io/TexLite/)
+A lightweight self-hosted alternative to Overleaf for *small, trusted* research
+teams. Use your existing LaTeX distribution, with no heavyweight service stack.
 
 [![CI](https://github.com/SWUFE-DB-Group/TexLite/actions/workflows/ci.yml/badge.svg)](https://github.com/SWUFE-DB-Group/TexLite/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/texlite?logo=npm&label=npm)](https://www.npmjs.com/package/texlite)
 
-![texLite preview](preview.png)
-
-For design goals, architecture, collaboration and compilation behavior, history,
-navigation and diagnostics, GitHub backup, and data-management decisions, see
-[DESIGN.md](DESIGN.md).
-
-## Requirements
-
-- Node.js 24 or newer
-- npm
-- git (optional; required only for the project-owner Git/GitHub integration)
-- latexmk
-- At least one configured engine: pdflatex, xelatex, or lualatex
+**Documentation:** English (this file) · [Operations](OPERATIONS.md) · [Design](DESIGN.md) · [简体中文](README.zh-CN.md)
 
-Check the host before initialization:
-
-~~~bash
-node --version
-npm --version
-latexmk --version
-xelatex --version
-# Optional, when Git/GitHub integration is needed:
-git --version
-~~~
-
-npm run init and application startup check latexmk and every engine in latex.allowedEngines. Git is deliberately excluded from this core check, so a host without Git can initialize and run TexLite normally. When a project owner opens the Git panel or invokes a Git/GitHub operation, TexLite checks git.binary on demand and shows an actionable error if Git is unavailable.
+**Website:** [TexLite GitHub Pages](https://swufe-db-group.github.io/TexLite/)
 
-Formatting is optional and runs in the browser. TexLite bundles the [`tex-fmt` npm package](https://www.npmjs.com/package/tex-fmt) (a WASM build) for `.tex`, `.cls`, and `.sty` files, and uses browser-side `bibtex-tidy` for `.bib` files. The editor settings panel accepts per-user/per-project TOML options for `tex-fmt`; no host formatter installation or PATH configuration is required.
+![TexLite workspace](preview-1.png)
+![TexLite project view](preview-2.png)
+
+## Why TexLite
+
+- **Own the writing environment.** Use the host's TeX installation and keep
+  sources, history, and compiled output in one local data directory.
+- **Collaborate without a large stack.** The default deployment is one Node.js
+  process, SQLite, and local files—plus real-time editing and source-level
+  comments for a small trusted team.
+
+## A practical distinction from Overleaf
+
+[Overleaf](https://www.overleaf.com/about/features-overview) is a strong choice
+when its hosted product or broader ecosystem is the right fit. TexLite addresses
+a narrower self-hosted use case:
+
+- A shared hosted service can queue, slow down, or time out at usage peaks.
+- Overleaf's open-source [Community Edition](https://github.com/overleaf/overleaf)
+  follows a more involved [Docker deployment path](https://docs.overleaf.com/on-premises/getting-started/what-is-the-overleaf-toolkit), and
+  [source comments are a Server Pro feature](https://docs.overleaf.com/on-premises/user-and-project-management/roles-and-permissions).
+- TexLite uses the server's existing TeX environment, runs as a small
+  single-host stack, and includes real-time source comments and replies.
+
+Self-hosting does not make every document compile faster: that still depends on
+the host and the document. It does give the team control over capacity, TeX
+updates, data location, and the collaboration workflow.
+
+For a desktop-first, individual workflow, start with
+[VS Code + LaTeX Workshop](https://github.com/James-Yu/LaTeX-Workshop) or
+[TeXstudio](https://texstudio.org/) instead. TexLite is purpose-built for
+shared browser writing, not a replacement for a personal IDE.
+
+## What the writing workflow includes
+
+- Projects with folders, ZIP import/export, tags, sharing, ownership transfer,
+  archiving, and a private per-user citation library.
+- CodeMirror editing with LaTeX/BibTeX highlighting, folding, completion,
+  optional Vim mode, formatting, spelling/grammar assistance, search/replace,
+  and source/PDF SyncTeX navigation.
+- Yjs-based collaborative source editing, active-session presence, comments
+  anchored to source text, replies, resolution, and permissions that let
+  reviewers comment without changing source.
+- `latexmk` compilation with selectable engines, project settings, structured
+  diagnostics, cached successful PDFs, downloadable artifacts, and optional
+  project-level `latexmkrc`.
+- Per-project history and owner-only Git/GitHub backup. Git is optional and is
+  checked only when its integration is used.
 
 ## Quick start
 
-### Global npm installation
+Install Node.js 24 or newer, `latexmk`, and at least one TeX engine such as
+`pdflatex`, `xelatex`, or `lualatex`. Git is needed only for the optional
+Git/GitHub integration.
 
-The published package provides a `texlite` executable. It keeps configuration
-and project data outside the global npm installation:
+After installation, `texlite requirements` checks the relevant host software
+and versions before initialization.
 
 ~~~bash
 npm install --global texlite
+texlite requirements
 texlite init
 texlite start
 texlite status
 ~~~
 
-Open http://127.0.0.1:3000. The service can be stopped or restarted from any
-working directory:
+Open <http://127.0.0.1:3000>. `texlite init` creates the configuration and the
+first administrator; public registration is deliberately unavailable.
 
-~~~bash
-texlite stop
-texlite restart
-texlite logs
-~~~
-
-The default configuration is
-`$XDG_CONFIG_HOME/texlite/texlite.config.json`, or
-`~/.config/texlite/texlite.config.json` when `XDG_CONFIG_HOME` is not set. The
-default data directory is `$XDG_DATA_HOME/texlite`, or
-`~/.local/share/texlite`. Use `--config PATH` or `TEXLITE_CONFIG` to select a
-different configuration file.
-
-`texlite serve` runs the server in the foreground and is suitable for Docker,
-systemd, and debugging. `start`, `status`, `stop`, `restart`, and `logs` use the
-PM2 dependency bundled with the package. Managed startup waits until the HTTP
-health endpoint is ready; `status` reports `unhealthy` if PM2 is running but the
-managed process is not actually serving TexLite. `restart` recreates the PM2
-entry so npm upgrades always use the current package paths and environment.
-Failed startup attempts are bounded instead of entering an unlimited restart
-loop.
-
-For a clean upgrade:
+For upgrades and routine management:
 
 ~~~bash
 npm update --global texlite
 texlite restart
-~~~
-
-Uninstalling the npm package does not remove the configuration or project data:
-
-~~~bash
-npm uninstall --global texlite
-~~~
-
-### Repository/source installation
-
-~~~bash
-npm ci
-cp texlite.config.example.json texlite.config.json
-export TEXLITE_CONFIG="$PWD/texlite.config.json"
-# Edit texlite.config.json if needed.
-npm run init
-npm run build
-npm start
-~~~
-
-The default server binds to localhost and does not expose public registration.
-The initialization command asks for the first administrator account; the server
-refuses to start until at least one active administrator exists.
-
-For a non-interactive initialization, set the following environment variables for that command only:
-
-~~~bash
-TEXLITE_INIT_USERNAME=admin \
-TEXLITE_INIT_DISPLAY_NAME=Administrator \
-TEXLITE_INIT_PASSWORD='use-a-password-of-at-least-8-characters' \
-npm run init
-~~~
-
-Avoid putting the password in shell history on a shared machine.
-
-## Development and verification
-
-Run the API/server watcher and Vite in separate terminals:
-
-~~~bash
-npm run dev       # API and server at http://127.0.0.1:3000
-npm run dev:web   # Vite UI at http://127.0.0.1:5173
-~~~
-
-Vite proxies /api requests to the server. Before a production-style run, use:
-
-~~~bash
-npm run typecheck
-npm test
-npm run build
-npm start
-~~~
-
-## Configuration
-
-Configuration path precedence is:
-
-1. `--config PATH` passed to the `texlite` executable;
-2. `TEXLITE_CONFIG`;
-3. `$XDG_CONFIG_HOME/texlite/texlite.config.json`;
-4. `~/.config/texlite/texlite.config.json`.
-
-Relative paths in the configuration are resolved relative to that configuration
-file. `storage.dataDir` defaults to `$XDG_DATA_HOME/texlite`, or
-`~/.local/share/texlite`. Set `storage.dataDir` in the configuration, or use
-`TEXLITE_DATA_DIR`, to choose another data directory. The production client
-bundle defaults to the `dist/client` directory inside the installed package;
-`TEXLITE_CLIENT_DIR` can override it for development or custom deployments.
-
-The example configuration is intentionally complete:
-
-~~~json
-{
-  "siteName": "TexLite",
-  "adminEmail": "admin@example.com",
-  "sessionDays": 14,
-  "server": { "host": "127.0.0.1", "port": 3000 },
-  "storage": { "dataDir": ".texlite" },
-  "uploads": { "maxFileSizeMB": 50 },
-  "pdf": { "loadingStrategy": "auto", "rangeThresholdMB": 5 },
-  "history": { "maxVersions": 200, "maxStorageMB": 128 },
-  "git": {
-    "binary": "git",
-    "operationTimeoutSeconds": 120,
-    "githubApiBaseUrl": "https://api.github.com"
-  },
-  "latex": {
-    "latexmk": "latexmk",
-    "defaultEngine": "xelatex",
-    "allowedEngines": ["pdflatex", "xelatex", "lualatex"],
-    "extraArgs": [],
-    "allowProjectLatexmkrc": true,
-    "compileTimeoutSeconds": 600,
-    "maxCompileJobs": 10
-  }
-}
-~~~
-
-The checked-in example uses `.texlite` as an explicit repository-development
-path. A configuration generated by `texlite init` uses the XDG data directory
-default described above instead.
-
-Important settings:
-
-- server.host and server.port: network bind address and port. Keep the host at 127.0.0.1 unless a separately secured deployment is intended.
-- storage.dataDir: SQLite database, project sources, compile output, and the Git token encryption key.
-- uploads.maxFileSizeMB: maximum size for a project upload, a ZIP entry, project files, and attachments. The default is 50 MB.
-- pdf.loadingStrategy: PDF.js transfer mode: `auto`, `full`, or `range`. In `auto` mode, PDFs at or below `pdf.rangeThresholdMB` use one cache-friendly response; larger PDFs use byte-range requests.
-- pdf.rangeThresholdMB: automatic Range threshold, defaulting to 5 MB. This is a deployment-level preview setting, not a project compiler option.
-- history.maxVersions: maximum number of ordinary, unlabeled versions retained per project. Initial and labeled versions are protected.
-- history.maxStorageMB: soft per-project limit for deduplicated history objects. The oldest ordinary versions are removed first; protected versions and the current internal baseline can exceed this limit.
-- latex.defaultEngine, latex.allowedEngines, latex.extraArgs: compile choices available in the UI.
-- latex.compileTimeoutSeconds: timeout for one compile job.
-- latex.maxCompileJobs: global number of concurrent LaTeX processes. Jobs for the same project and root document are serialized; newer source versions supersede older queued requests. Different root documents use independent workspaces and may compile concurrently within this global limit.
-- Compilation copies a short-lived immutable source snapshot, then runs `latexmk` outside the ordinary project-operation queue. Editing and retained-PDF reads can continue; Git checkout, history restore, deletion, and compile-cache cleanup wait for active compilation to finish.
-- latex.allowProjectLatexmkrc: allow a project to supply a multi-line latexmkrc. A project rc file is executable Perl configuration and should only be enabled for trusted users.
-
-Before every compile TexLite passes `-norc` to latexmk. Therefore a `.latexmkrc`
-included directly in an uploaded ZIP, Git checkout, or project source is ignored.
-The file is read only when the owner explicitly selects it in Project Settings,
-where TexLite passes it with `-r`.
-
-### Effective defaults and startup validation
-
-When a setting is omitted, texLite uses the following built-in defaults (the
-generated example file may choose to show an explicit value such as an admin
-email):
-
-| Setting | Effective default |
-| --- | --- |
-| `siteName` | `TexLite` |
-| `adminEmail` | empty |
-| `server.host` / `server.port` | `127.0.0.1` / `3000` |
-| `storage.dataDir` | `$XDG_DATA_HOME/texlite` or `~/.local/share/texlite` |
-| `clientDir` | `dist/client` inside the installed package |
-| `sessionDays` | `14` |
-| `uploads.maxFileSizeMB` | `50` MB |
-| `pdf.loadingStrategy` | `auto` |
-| `pdf.rangeThresholdMB` | `5` MB |
-| `history.maxVersions` | `200` ordinary versions per project |
-| `history.maxStorageMB` | `128` MB per project (soft limit) |
-| `latex.latexmk` | `latexmk` |
-| `latex.defaultEngine` | `xelatex` |
-| `latex.allowedEngines` | `pdflatex`, `xelatex`, `lualatex` |
-| `latex.extraArgs` | `[]` |
-| `latex.allowProjectLatexmkrc` | `true` |
-| `latex.compileTimeoutSeconds` | `600` seconds |
-| `latex.maxCompileJobs` | `10` |
-| `git.binary` / `git.operationTimeoutSeconds` | `git` / `120` seconds |
-| `git.githubApiBaseUrl` | `https://api.github.com` |
-
-Configuration is validated before environment checks, database opening, or
-the HTTP listener starts. Explicit values are never silently replaced by a
-default. The accepted ranges are: port `1–65535`, sessions `1–3650` days,
-upload size `1–2048` MB, history versions `10–5000`, history storage
-`16–102400` MB, PDF Range threshold `1–2048` MB, compile timeout `1–3600` seconds, compile jobs `1–32`,
-and Git timeout `1–3600` seconds. Engine names must be supported, unique, and
-the allowed-engine list must include the selected default engine. Data and
-project paths must not point at files (the data directory cannot be the
-filesystem root); a missing data directory must have an existing writable
-parent. The GitHub API endpoint must be an `http://` or `https://` URL.
-
-Invalid JSON types, empty required strings, malformed integers (including
-decimal or non-numeric environment overrides), unsupported engines, invalid
-URLs, and unusable paths stop startup with the setting name, expected value,
-and a remediation hint. The same validation runs during `npm run init`, so a
-configuration can be checked before creating the first administrator.
-
-Environment variables override the corresponding file values:
-
-~~~text
-TEXLITE_CONFIG
-XDG_CONFIG_HOME                 XDG_DATA_HOME
-TEXLITE_SITE_NAME             TEXLITE_ADMIN_EMAIL
-TEXLITE_HOST                  TEXLITE_PORT
-TEXLITE_DATA_DIR              TEXLITE_CLIENT_DIR
-TEXLITE_SESSION_DAYS          TEXLITE_MAX_UPLOAD_SIZE_MB
-TEXLITE_PDF_LOADING_STRATEGY TEXLITE_PDF_RANGE_THRESHOLD_MB
-TEXLITE_HISTORY_MAX_VERSIONS TEXLITE_HISTORY_MAX_STORAGE_MB
-TEXLITE_LATEXMK               TEXLITE_DEFAULT_ENGINE
-TEXLITE_COMPILE_TIMEOUT       TEXLITE_MAX_COMPILE_JOBS
-TEXLITE_GIT                   TEXLITE_GIT_TIMEOUT
-TEXLITE_GITHUB_API_URL
-~~~
-
-texLite does not run tlmgr or install missing packages. Updating TeX Live on the host changes the environment used by the next compile.
-
-## Service management
-
-For a global npm installation, the lifecycle commands use the bundled PM2
-runtime. No separate global PM2 installation is needed:
-
-~~~bash
-texlite start
-texlite status
 texlite logs
-texlite restart
-texlite stop
-~~~
-
-`texlite status` uses a colored, systemctl-style terminal view. Use
-`texlite status --json` for scripts and monitoring integrations.
-
-`texlite doctor` validates configuration, paths, LaTeX, and the administrator;
-add `--git` to check the optional Git integration. `texlite config` prints the
-effective paths and values. `texlite serve` keeps the process in the foreground
-and does not start PM2.
-
-<details>
-<summary>Repository deployment with a separately installed PM2</summary>
-
-For repository deployments, `ecosystem.config.cjs` and the npm PM2 wrappers are
-also available. It deliberately runs one forked instance (`instances: 1`);
-cluster mode is not supported because collaboration state, the compile queue,
-SQLite, and the project filesystem are local to one process.
-
-~~~bash
-npm install --global pm2
-npm run build
-pm2 start ecosystem.config.cjs
-pm2 status
-pm2 logs texlite
 ~~~
 
-The repository wrappers are `npm run pm2:start`, `npm run pm2:restart`,
-`npm run pm2:stop`, `npm run pm2:delete`, `npm run pm2:logs`, and
-`npm run pm2:save`.
+`texlite serve` runs in the foreground for debugging, Docker, or systemd.
+`start`, `stop`, `restart`, `status`, and `logs` use the PM2 runtime bundled
+with the npm package. Run `texlite help` for the complete command list.
 
-After deploying new code:
+## Documentation map
 
-~~~bash
-npm run build
-pm2 restart texlite --update-env
-~~~
-
-To keep the process across reboots, run the command printed by pm2 startup, then save the process list:
-
-~~~bash
-pm2 save
-~~~
-
-Useful lifecycle commands are pm2 stop texlite, pm2 restart texlite, pm2 delete texlite, and pm2 monit.
-
-</details>
-
-## Security boundaries
+| Need | Read |
+| --- | --- |
+| Installation, configuration paths, effective defaults, environment overrides, service management, backups, and security boundaries | [Operations guide](OPERATIONS.md) |
+| Collaboration, source persistence, compilation isolation, history, and design trade-offs | [Design](DESIGN.md) |
+| Testing an npm package before publication | [NPM testing guide](NPM_TESTING.md) |
+| Complete configuration starting point | [texlite.config.example.json](texlite.config.example.json) |
 
-texLite is designed for trusted users on localhost. The default compiler disables shell escape, does not concatenate shell commands, and enforces compile timeouts and concurrency limits. Nevertheless, LaTeX itself and a project latexmkrc are not a security sandbox. Before exposing texLite to an untrusted network or public registration, add an isolated compiler sandbox and an appropriate authentication/reverse-proxy layer.
+## Scope and security
 
-## License and status
+TexLite is a single-host application for trusted users. It is not a compiler
+sandbox: LaTeX and an enabled project `latexmkrc` can execute powerful local
+behaviour. Keep the default `127.0.0.1` bind unless you add the authentication,
+network controls, and isolated compiler environment appropriate for an
+untrusted deployment.
 
-texLite is licensed under the GNU Affero General Public License v3.0. See [LICENSE](LICENSE). If you need proprietary modifications or commercial terms different from AGPL-3.0, contact the copyright holder for a separate commercial license.
+## License
 
-This repository is an early, single-host application rather than a drop-in replacement for Overleaf. Review and adapt the deployment, backup, and security settings for the environment in which it will run.
+TexLite is licensed under the GNU Affero General Public License v3.0; see
+[LICENSE](LICENSE). For proprietary modifications or commercial terms that
+differ from AGPL-3.0, contact the copyright holder.