Using and hosting the documentation The documentation is a Haskell WAI application served by Warp. HTML is rendered with ihp-hsx. It needs no database, JavaScript framework, Node.js, external search service, or CDN. The site is separate from the agent runtime: reading a page does not start an agent or connect a model account. Find a guide Use the navigation groups to select a page. Previous and next links follow the guide order. On narrow screens, open Menu for the navigation and On this page for section links. These section links also work without JavaScript. Search submits your query to this documentation server, not to a model. All space-separated terms must occur in the title, description, or page text. Matching ignores letter case and uses substrings, not regular expressions or fuzzy spelling. Title matches are ranked first. Queries are limited to 200 characters; an empty query does not return every page. For example, search session export. If no guide matches, remove a term or search the exact command name. Search indexes the published pages; engineering Markdown files elsewhere in the repository are not included. Published operator procedures are available in Deployment, HTTP server, runtime daemon, and native integration. These distinguish implemented interfaces from application UX that is not shipped by this repository. Design notes remain separate rather than being presented as supported user workflows. Reading controls and exports Ctrl-K or Command-K focuses search when JavaScript is available. Theme selects Auto, Light, or Dark and is remembered in this browser. Copy buttons preserve the displayed code text; clipboard access requires HTTPS or localhost. Without JavaScript, reading, form-based search, section links and text exports still work. Each page has a text export derived from the same HTML content. The documentation index for agents lists all exports. These are plain text, not a separate Markdown source tree. A copied example remains an instruction to review, not proof it has run on your machine. Start locally From a checkout of this repository: nix build .#docs nix run .#docs curl --fail http://127.0.0.1:4321/ The server runs in the foreground. Open a second terminal for the curl check. Expect an HTML document and HTTP 200. Stop the foreground server with Ctrl-C. The build produces result/bin/documentation-server and installed assets; it does not produce a static directory to upload. Server settings Environment variable | Default | Behavior | DOCS_HOST | 127.0.0.1 | Listening address. Keep loopback behind a reverse proxy. | DOCS_PORT | 4321 | Integer TCP port from 1 to 65535. | DOCS_ASSET_DIRECTORY | Installed public directory | Override only when supplying a complete matching asset set. | Assets are read at application startup. Restart after changing an override. Only registered asset names are served; request paths do not become arbitrary filesystem reads. To deliberately listen on all interfaces: DOCS_HOST=0.0.0.0 DOCS_PORT=8080 nix run .#docs This exposes the site to other machines. There is no built-in authentication or TLS. Do not place private documentation on a public listener without an authenticated reverse proxy and appropriate network restrictions. Supervise a service On a Linux host with systemd, first build and retain a release outside a temporary checkout. An out-link keeps its Nix closure reachable by garbage collection: nix build .#docs --out-link /srv/haskell-agent-documentation/release The directory must already exist and be writable by your deployment account. Create a dedicated unprivileged service user, then adapt this unit: [Unit] Description=Haskell Agent documentation After=network.target [Service] User=documentation Group=documentation ExecStart=/srv/haskell-agent-documentation/release/bin/documentation-server Environment=DOCS_HOST=127.0.0.1 Environment=DOCS_PORT=4321 Restart=on-failure RestartSec=5 NoNewPrivileges=true PrivateTmp=true ProtectSystem=strict ProtectHome=true [Install] WantedBy=multi-user.target Install it as /etc/systemd/system/haskell-agent-documentation.service, reload systemd, and start it: sudo systemctl daemon-reload sudo systemctl enable --now haskell-agent-documentation systemctl status haskell-agent-documentation journalctl -u haskell-agent-documentation -n 50 curl --fail http://127.0.0.1:4321/ This is a deployment example, not a recorded systemd deployment test. On macOS, use a launchd service with the same installed executable and environment; do not install a Linux unit. Reverse proxy and readiness Serve the application at the domain root. Root-relative links do not support mounting it below an arbitrary URL prefix. In an existing TLS-enabled Nginx server, proxy to loopback: location / { proxy_pass http://127.0.0.1:4321; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; } Provision the domain and certificate using your normal operator procedure. Check both the local upstream and the public HTTPS address. There is no separate health endpoint: use GET / and a known asset such as /documentation.css. A 502 usually means the proxy cannot reach the listener. Missing styles suggest mismatched assets or an unsupported URL prefix. Upgrade and recover - Record the current release store path and retain its out-link. - Build the reviewed revision to a separate candidate out-link. - Run the candidate on a different loopback port and check a page, search, text export and stylesheet. - Update the service executable path to the candidate and restart the service. - Check the public address. If it fails, restore the previous executable path and restart. Keep the previous release until recovery is no longer needed. No documentation database migration is needed. A process restart interrupts in-flight requests; browsers can retry read requests. An invalid port, occupied address, or incomplete asset directory can prevent startup. Inspect the service log rather than repeatedly restarting without correcting the cause. Maintain pages Edit HSX under docs/src/Documentation/Pages. Register each module in Documentation.Content and the Cabal exposed-module list. Add stable heading IDs, cross-links, examples and regression assertions. Regenerate docs/package.nix with cabal2nix after Cabal changes. New assets require both the Cabal data-file entry and the application's explicit asset registration, plus an asset-route regression test in docs/test/Main.hs. Follow docs/README.md for the GHCi development loop and validation commands. Page tests verify rendering and links, not every documented product behavior.