From 377b5a28b61436214a072da72ffd89a0a82d04f4 Mon Sep 17 00:00:00 2001 From: Federico Jaramillo Martinez Date: Wed, 1 Jul 2026 22:39:47 +0200 Subject: [PATCH] docs: align package management website docs --- docs/config.html | 83 ++++++++++++++++++++++++++++++++++++---------- docs/index.html | 2 +- docs/machines.html | 16 +++++---- docs/plugins.html | 22 ++++++++---- 4 files changed, 92 insertions(+), 31 deletions(-) diff --git a/docs/config.html b/docs/config.html index a610588..059579b 100644 --- a/docs/config.html +++ b/docs/config.html @@ -3,10 +3,10 @@ - Configure PI WEB — config files, paths, and session tools + Configure PI WEB — config files, uploads, paths, and session tools @@ -14,7 +14,7 @@ @@ -23,7 +23,7 @@ @@ -81,7 +81,7 @@

PI WEB configuration covers the machine-local and project-local settings you usually need: bind address, trusted development-host settings, UI preferences, PI WEB plugin enablement, file-explorer path access, - upload limits, and session-daemon tools. + manual upload defaults, upload limits, and session-daemon tools.

@@ -96,6 +96,7 @@ Project config Config matrix External path access + Manual uploads Session tools Completion tools @@ -113,10 +114,11 @@ config by opening that machine directly or changing files on that machine.

- Pi package settings are separate from PI WEB config. They live in Pi's package-manager settings and are - managed by Pi (pi install, pi remove, pi update) or - Settings → Pi packages. The PI WEB plugins config key only enables or - disables discovered PI WEB browser plugins. + Pi package settings are separate from PI WEB config. They live in Pi's package-manager settings on the + target machine and are managed by Pi (pi install, pi remove, pi update) or + Settings → Pi packages. In a federated setup, Settings → Pi packages + targets the currently selected machine; the PI WEB plugins config key only enables or + disables discovered PI WEB browser plugins for the gateway you opened.

If you installed services with a custom config path, rerun @@ -128,10 +130,14 @@

Precedence and reloads

-

Runtime values are resolved in this order:

+

Machine-global runtime values are resolved in this order:

- 
defaults → config file → environment overrides
+ 
defaults → global config file → environment overrides
+

+ Supported project-local settings are then applied for that project's workspaces. For upload defaults, + <project>/.pi-web/config.json overrides the global value. +

Environment overrides include PI_WEB_HOST, PI_WEB_PORT / PORT, PI_WEB_ALLOWED_HOSTS, PI_WEB_MAX_UPLOAD_BYTES, PI_WEB_SPAWN_SESSIONS, @@ -142,8 +148,9 @@

  • maxUploadBytes: restart both the web/API process and the session daemon.
  • spawnSessions / subsessions: restart the session daemon.
  • pathAccess: applies on the next request; existing file views may need a browser refresh.
    • +
  • uploads.defaultFolder: applies to newly opened Files upload dialogs and new direct drag/drop batches after config/workspace refresh.
  • plugins: reload the browser tab after changing PI WEB plugin enablement.
    • -
  • Pi package install/remove/update: not a PI WEB config key; after a mutation, type /reload in each idle PI WEB session to refresh Pi runtime resources such as extensions, skills, prompt templates, themes, and context/system prompt files as supported by Pi. Reload the browser page separately for PI WEB browser plugin changes. A routine session daemon restart is not required.
    • +
  • Pi package install/remove/update: not a PI WEB config key; after a mutation, type /reload in each idle PI WEB session on the target machine to refresh Pi runtime resources such as extensions, skills, prompt templates, themes, and context/system prompt files as supported by Pi. Reload the browser page separately for PI WEB browser plugin changes. A routine session daemon restart is not required.
  • shortcuts: saved settings apply in the browser after config refresh/save.
    • @@ -167,6 +174,9 @@ "pathAccess": { "allowedPaths": ["~/SDKs", "/opt/reference"] }, + "uploads": { + "defaultFolder": ".pi-web/uploads" + }, "maxUploadBytes": 67108864, "spawnSessions": true, "subsessions": false, @@ -187,8 +197,7 @@

    Project-local config

    Project-local config lives at <project>/.pi-web/config.json. Use it for settings that should - follow a repository. When a project config defines pathAccess, PI WEB merges it after the - global path list. + follow a repository.

    @@ -199,13 +208,25 @@ "version": 1, "pathAccess": { "allowedPaths": ["~/SDKs", "/opt/reference"] + }, + "uploads": { + "defaultFolder": "manual/uploads" } }

    - Project-local pathAccess.allowedPaths entries must still be host-absolute or - ~-prefixed; relative roots are not supported. Plugins may own separate project files, such as - .pi-web/tasks.json for the built-in Workspace Tasks plugin. + Project-local pathAccess.allowedPaths entries are merged after the global list and deduplicated. + Paths must still be host-absolute or ~-prefixed; relative roots are not supported. +

    +

    + Project-local uploads.defaultFolder overrides the global upload destination for workspaces in + that project. Current PI WEB servers include this workspace-effective value on local and federated + workspace responses; older remote servers may omit it and the browser falls back to the global/default + upload folder. +

    +

    + Plugins may own separate project files, such as .pi-web/tasks.json for the built-in Workspace + Tasks plugin.

    @@ -262,6 +283,14 @@ Merges: global roots first, then project roots; duplicates removed Next file request; refresh existing views if needed + + Manual file upload default folder + uploads.defaultFolder + — + Global + project + Overrides: project value wins for workspaces in that project; otherwise global/default applies + New Upload dialogs and direct drag/drop batches after config/workspace refresh + Upload/body limit maxUploadBytes @@ -428,6 +457,26 @@
    +
    +

    Manual upload defaults

    +

    + The Files panel can upload files by dropping them onto the panel or by using the toolbar + Upload button. uploads.defaultFolder sets the workspace-effective default + destination. The built-in default is .pi-web/uploads; a project-local value overrides the + global value for workspaces in that project. +

    +

    + The value must be a non-empty workspace-relative folder. PI WEB normalizes repeated separators and + backslashes to /, and rejects absolute paths or .. traversal. In the upload + dialog only, clearing the destination field uploads that batch to the workspace root. +

    +

    + Manual uploads use the workspace file-write path: paths stay workspace-relative, parent folder creation is + enabled by default, and overwrite is disabled by default. Browser-owned XHR progress is shown per + batch/file, and conflicts or errors stay visible in the upload progress UI. +

    +
    +

    Session daemon tools

    spawnSessions

    diff --git a/docs/index.html b/docs/index.html index e17f81b..d1a1d31 100644 --- a/docs/index.html +++ b/docs/index.html @@ -251,7 +251,7 @@

    Your device is replaceable. The sessions are not. Move between laptop, phone, tablet, and desktop without moving the development environment. Under the hood, PI WEB coordinates the running sessions, - files, terminals, and remote machines like a browser-based control plane. + files, terminals, Pi package management, and remote machines like a browser-based control plane.

    diff --git a/docs/machines.html b/docs/machines.html index 665f222..38099c1 100644 --- a/docs/machines.html +++ b/docs/machines.html @@ -6,7 +6,7 @@ PI WEB fleet — remote Pi web UI machines @@ -81,7 +81,7 @@

    Most PI WEB setups only need one runtime. When you do have more than one, machine federation lets the PI WEB instance you opened act as a gateway to other trusted runtimes while each machine keeps its own repositories, - credentials, sessions, and plugins. + credentials, sessions, Pi package settings, and plugins.

    @@ -111,7 +111,7 @@

    After registration, the browser keeps talking to the current PI WEB origin. The gateway contacts the selected remote PI WEB server and routes that machine's projects, workspaces, sessions, files, git state, - activity, and terminals to the browser UI. + activity, terminals, and Pi package-management operations to the browser UI.

    @@ -125,7 +125,7 @@ PI WEB gateway you opened │ ├─ [ Remote PI WEB runtime A ] │ ↓ selected machine - │ projects, workspaces, sessions, terminals, plugins + │ projects, workspaces, sessions, terminals, Pi packages, plugins │ └─ [ Remote PI WEB runtime B ]
    @@ -151,7 +151,7 @@ PI WEB gateway you opened
    ⌁

    Local ownership

    -

    Each target machine keeps its own Pi auth, sessions, worktrees, terminal state, and plugins.

    +

    Each target machine keeps its own Pi auth, sessions, worktrees, terminal state, Pi package settings, and plugins.

    @@ -213,6 +213,7 @@ PI WEB gateway you opened
  • Pi sessions, transcripts, prompts, model controls, and commands.
  • Activity indicators and realtime updates.
  • Terminals and terminal command runs.
    • +
  • Pi package listing, install, remove, and update from Settings → Pi packages when supported by the target PI WEB runtime.
  • Remote plugins from the selected machine.
    • @@ -220,8 +221,9 @@ PI WEB gateway you opened

    Credentials stay on the target machine

    - Model-provider credentials, Pi configuration, OAuth state, repositories, and active session runtimes stay - on the selected target machine. The gateway does not copy them into its own Pi configuration. + Model-provider credentials, Pi configuration, Pi package-manager settings, OAuth state, repositories, and + active session runtimes stay on the selected target machine. The gateway does not copy them into its own + Pi configuration.

    @@ -323,7 +331,9 @@ After editing, check the manifest endpoint and browser-console failure cases.

    This surface is only for PI WEB plugin enablement. To install, remove, or update Pi packages that may - provide plugins or other Pi resources, use Settings → Pi packages. + provide plugins or other Pi resources, use Settings → Pi packages. In a federated setup, + the Pi packages panel targets the selected machine; the PI WEB plugins panel still controls gateway plugin + enablement.