Agent Notes

This project is expected to run locally using split systemd user services:

• pi-webui-sessiond.service runs npm run start:sessiond in non-autoreload, non-auto-restart mode.
• pi-webui-ui-dev.service runs the web/API and Vite UI in dev autoreload mode with npm run dev:web and npm run dev:client.

When working on this project, assume the session runtime owner is long-lived and separate from the autoreloading UI/API process. Browser disconnects and UI/API restarts should not stop active Pi sessions.

If you make changes that affect src/server/sessiond.ts, session runtime ownership, the session daemon protocol, or any code path only loaded by the session daemon, inform the user that a manual restart of the session daemon is needed.

Changes to the web/API/UI side generally only require the pi-webui-ui-dev.service autoreload/restart path.

Publication policy

Publishing to npm is allowed through the standard GitHub Actions release workflow. Use .agents/skills/npm-release-via-github-actions/SKILL.md for the full release process. Do not run npm publish locally; always route publishing through GitHub Releases triggering the publish workflow.

Security-audit exception policy

IGNORED.md is the canonical project policy and register for a narrowly scoped upstream-only, non-bundled dependency-audit exception. A Security Auditor may mark a security gate as pass with documented exception only after verifying every condition in that file and the PM records approval and evidence in the release handoff.

The exception never applies to secrets, PI WEBUI source findings, direct or production dependency findings, dependency-path changes introduced by the release candidate, or findings not specifically registered in IGNORED.md. It does not waive the upstream Pi package's security obligations. Do not create a GitHub Release or publish to npm until the Security Auditor has recorded this evidence and the PM has approved the documented exception.

Documentation boundaries

README.md is a concise landing page and quick start. Keep it focused on what PI WEBUI is, basic requirements, the shortest supported install path, essential commands, the core model, and links to detailed documentation.

Put installation variants, troubleshooting, configuration details, operational behavior, architecture, edge cases, and exhaustive explanations under docs/. Avoid duplicating detailed documentation in the README; link to its canonical location instead.

Use .agents/skills/documentation-guide/SKILL.md whenever writing, modifying, reviewing, or planning user-facing documentation.

Testing guidance

Project-specific testing rules live in .agents/skills/testing-guide/SKILL.md.

Use that skill whenever writing, modifying, reviewing, or planning tests, closing coverage gaps, triaging test failures, or creating test helpers/harnesses. Keep detailed testing conventions there rather than growing this top-level orientation file.

Client application URL convention

• Build PI WEBUI-owned browser paths as application-relative references without a leading slash, for example api/... and pi-webui-plugins/....
• Encode every dynamic path segment with encodeURIComponent; encode query values, using URLSearchParams for multi-field queries.
• Resolve each reference exactly once at the browser boundary: ordinary JSON HTTP paths go to request(), direct browser APIs receive URLs from helpers backed by resolveAppUrl(), and WebSockets use resolveAppWebSocketUrl().
• Name helpers returning unresolved application references with a Path suffix and helpers returning browser-ready absolute values with a Url suffix.
• Plugin module references must go through resolvePluginModuleUrl(). Its leading-slash handling is the documented rolling-compatibility exception; do not introduce other leading-root app references.
• Pre-JavaScript HTML assets use Vite %BASE_URL%; PWA manifest references stay ./-relative. External links, data URLs, and module-relative plugin assets are not application paths.
• To assess deviations, search production client code for raw fetch, WebSocket, XMLHttpRequest, URL-bearing DOM attributes, and leading /api or /pi-webui-plugins literals. Every app-owned result must follow one of the boundaries above.
• Published nested deployments require a canonical trailing slash; the reverse proxy must redirect a slashless prefix before serving the app.

Configuration conventions

• $PI_WEBUI_DATA_DIR (~/.pi-webui by default) contains PI WEBUI-managed state such as projects.json and machines.json; do not treat it as the user-editable config API.
• Global user/machine config lives at $PI_WEBUI_CONFIG or ~/.config/pi-webui/config.json.
• Project-local PI WEBUI core config should use one commit-able file: <project>/.pi-webui/config.json.
• Core features should add keys to these config files, not create one project file per feature.
• Plugins may own separate project config files, such as .pi-webui/tasks.json.