docs: organize docs/ into purpose folders with consistent naming

Sort docs/ into guide/ contributing/ architecture/ roadmap/ and rename
to consistent kebab-case (USER->guide/install-and-use, FOOTPRINT->
architecture/system-footprint, frontend-modularization->architecture/
webui-architecture, etc.). Add a docs/README.md index and a docs/
CONTRIBUTING.md pointer so the forge still surfaces the contributing
guide. Fix every reference (README, init.sh comments, frontend code
comments, and the USER<->DEVELOPMENT cross-links). History preserved
via git mv. Root stays README.md + CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: librelad <librelad@digitalangels.vip>

README.md

@@ -21,7 +21,7 @@ toggle — it's the whole point.
 
 The entire platform is **free software under the [GNU AGPLv3](LICENSE)**.
 Self-host it and you get **everything** — every feature, no paywalls, no
-telemetry. See [our Promise](docs/PROMISE.md) for exactly what that means.
+telemetry. See [our Promise](docs/guide/promise.md) for exactly what that means.
 
 ## What you get
 
@@ -45,9 +45,9 @@ data on separate disks with `--system-dir=` / `--containers-dir=` / `--backups-d
 
 ## Documentation
 
-- **[docs/USER.md](docs/USER.md)** — install, place data on separate disks/drives,
+- **[docs/guide/install-and-use.md](docs/guide/install-and-use.md)** — install, place data on separate disks/drives,
   update, back up, uninstall.
-- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** — run a dev copy, cut stable/edge
+- **[docs/contributing/development.md](docs/contributing/development.md)** — run a dev copy, cut stable/edge
   releases, and test them before publishing.
 
 ## LibrePortal Connect (optional)
@@ -59,11 +59,11 @@ different: we work like a **courier carrying a sealed box.** We move your data
 between your devices and store backup copies, but it stays locked and *you*
 hold the only key — we can't open it, and we never run your apps for you.
 **Everything we offer, you can also set up yourself for free.**
-[Our Promise](docs/PROMISE.md) spells out exactly where that line sits.
+[Our Promise](docs/guide/promise.md) spells out exactly where that line sits.
 
 ## Contributing
 
-PRs welcome — see [CONTRIBUTING.md](docs/CONTRIBUTING.md). We use a lightweight
+PRs welcome — see [CONTRIBUTING.md](docs/contributing/contributing.md). We use a lightweight
 DCO sign-off (`git commit -s`), no CLA.
 
 ## Acknowledgments

containers/libreportal/frontend/components/backup/index.js

@@ -1,6 +1,6 @@
 // components/backup/index.js — Backup Center as a self-contained feature module.
 //
-// FIRST page migrated to the feature-module contract (docs/frontend-modularization.md).
+// FIRST page migrated to the feature-module contract (docs/architecture/webui-architecture.md).
 // The kernel drives mount()/unmount() for the /backup route instead of
 // spa.js's handleBackup(). The heavy controller (backup-page.js, ~129KB) is
 // still lazy-loaded on first mount, so cold-load cost is unchanged.

containers/libreportal/frontend/components/manifest.dev.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "note": "Phase-0 hand-committed manifest (to be replaced by the generated /data/webui/generated/features.json once the scan generator lands — see docs/frontend-modularization.md). 'module' is the feature's self-registering index.js; the kernel loads these from here so they no longer need <script> tags in index.html. 'handler' names the LibrePortalSPAClean method kept as the fallback during the strangler migration; 'navId' is the topbar element id for active-state highlighting.",
+  "note": "Phase-0 hand-committed manifest (to be replaced by the generated /data/webui/generated/features.json once the scan generator lands — see docs/architecture/webui-architecture.md). 'module' is the feature's self-registering index.js; the kernel loads these from here so they no longer need <script> tags in index.html. 'handler' names the LibrePortalSPAClean method kept as the fallback during the strangler migration; 'navId' is the topbar element id for active-state highlighting.",
   "features": [
     {
       "id": "dashboard",

containers/libreportal/frontend/core/kernel/js/feature-registry.js

@@ -1,7 +1,7 @@
 // kernel/feature-registry.js — the single source of truth for "what pages exist".
 //
 // This is the first piece of the feature-module architecture (see
-// docs/frontend-modularization.md). It replaces the four hand-maintained
+// docs/architecture/webui-architecture.md). It replaces the four hand-maintained
 // registries the SPA grew over time:
 //   1. the eager <script> list in index.html,
 //   2. spa.js's hardcoded `routes` Map (setupRoutes),

containers/libreportal/frontend/core/kernel/js/lifecycle.js

@@ -1,6 +1,6 @@
 // kernel/lifecycle.js — the MountContext a feature module receives.
 //
-// Part of the feature-module architecture (docs/frontend-modularization.md §2.4).
+// Part of the feature-module architecture (docs/architecture/webui-architecture.md).
 // A feature exports mount(ctx)/unmount(ctx); the SPA shell drives them and hands
 // in this context. In this first form the content helpers delegate to the SPA
 // shell (so rendering is byte-identical to the legacy handlers), plus a teardown

containers/libreportal/frontend/index.html

@@ -106,7 +106,7 @@
   <script src="/core/boot/js/system-orchestrator.js"></script>
   <!-- Feature-module kernel. Currently passive: defines window.LP.features and
        loads the page manifest; spa.js consults it for routing. See
-       docs/frontend-modularization.md. -->
+       docs/architecture/webui-architecture.md. -->
   <script src="/core/kernel/js/feature-registry.js"></script>
   <script src="/core/kernel/js/services.js"></script>
   <script src="/core/kernel/js/lifecycle.js"></script>

docs/CONTRIBUTING.md

@@ -1,40 +1,6 @@
-# Contributing to LibrePortal
+# Contributing
 
-Thanks for wanting to help — LibrePortal is built in the open, and
-contributions are genuinely welcome.
+The contributing guide lives at **[contributing/contributing.md](contributing/contributing.md)**.
 
-## Ground rules
-
-- LibrePortal is **AGPLv3**. By contributing, your work is offered under that
-  same license (see the DCO below).
-- **Match the surrounding code** — keep it simple and readable, and follow
-  the style of the file you're editing.
-- Keep pull requests focused: one change per PR where you can.
-
-## Developer Certificate of Origin (DCO)
-
-We use the [DCO](https://developercertificate.org/) instead of a CLA — no
-paperwork, just a sign-off certifying you have the right to submit your code.
-
-Add a `Signed-off-by` line to every commit by committing with `-s`:
-
-```bash
-git commit -s -m "your message"
-```
-
-That appends:
-
-```
-Signed-off-by: Your Name <you@example.com>
-```
-
-By signing off, you agree to the DCO: that you wrote the patch (or otherwise
-have the right to submit it) and that it may be included under the project's
-AGPLv3 license.
-
-## Bugs & ideas
-
-Open an issue — clear steps to reproduce and your environment details help a
-lot.
-
-Thanks for helping keep self-hosting free and open. 🕊️
+(This pointer stays at `docs/` so the forge surfaces it in the new-issue/PR flow;
+the full guide and the rest of the docs are sorted under [docs/](README.md).)

docs/README.md

@@ -0,0 +1,19 @@
+# LibrePortal docs
+
+Sorted by audience. Start with **guide/** if you're running LibrePortal,
+**contributing/** if you're hacking on it.
+
+## guide/ — using LibrePortal
+- [install-and-use.md](guide/install-and-use.md) — install, place data on separate disks, update, back up, uninstall.
+- [promise.md](guide/promise.md) — the LibrePortal Promise: free/open, no paywalls, no telemetry, in plain language.
+
+## contributing/ — working on LibrePortal
+- [contributing.md](contributing/contributing.md) — how to contribute (DCO sign-off, no CLA).
+- [development.md](contributing/development.md) — run a dev copy, cut stable/edge releases, test before publishing.
+
+## architecture/ — how it's built
+- [system-footprint.md](architecture/system-footprint.md) — everything LibrePortal places outside its data roots, and who owns it.
+- [webui-architecture.md](architecture/webui-architecture.md) — the WebUI component-module system (as-built).
+
+## roadmap/ — where it's going
+- [updates-and-distribution.md](roadmap/updates-and-distribution.md) — vision for hotfixes, the "Updates & Improvements" front door, and registry-not-marketplace distribution.

docs/contributing/contributing.md

@@ -0,0 +1,40 @@
+# Contributing to LibrePortal
+
+Thanks for wanting to help — LibrePortal is built in the open, and
+contributions are genuinely welcome.
+
+## Ground rules
+
+- LibrePortal is **AGPLv3**. By contributing, your work is offered under that
+  same license (see the DCO below).
+- **Match the surrounding code** — keep it simple and readable, and follow
+  the style of the file you're editing.
+- Keep pull requests focused: one change per PR where you can.
+
+## Developer Certificate of Origin (DCO)
+
+We use the [DCO](https://developercertificate.org/) instead of a CLA — no
+paperwork, just a sign-off certifying you have the right to submit your code.
+
+Add a `Signed-off-by` line to every commit by committing with `-s`:
+
+```bash
+git commit -s -m "your message"
+```
+
+That appends:
+
+```
+Signed-off-by: Your Name <you@example.com>
+```
+
+By signing off, you agree to the DCO: that you wrote the patch (or otherwise
+have the right to submit it) and that it may be included under the project's
+AGPLv3 license.
+
+## Bugs & ideas
+
+Open an issue — clear steps to reproduce and your environment details help a
+lot.
+
+Thanks for helping keep self-hosting free and open. 🕊️

docs/contributing/development.md

@@ -1,7 +1,7 @@
 # LibrePortal — Development & Releases
 
 How to run a development copy, cut stable/edge releases, and test them before they
-go out. For installing/using LibrePortal, see [USER.md](USER.md).
+go out. For installing/using LibrePortal, see [install & use guide](../guide/install-and-use.md).
 
 ## Mental model (read this first)
 

docs/guide/install-and-use.md

@@ -1,11 +1,11 @@
 # LibrePortal — Install & Use
 
 How to install, place, update, and remove LibrePortal. For building releases or
-running a dev copy, see [DEVELOPMENT.md](DEVELOPMENT.md).
+running a dev copy, see [development guide](../contributing/development.md).
 
 > **Note:** the `get.libreportal.org` host isn't live yet. Until it is, install
 > from a local release artifact or a git/local checkout — see
-> [DEVELOPMENT.md](DEVELOPMENT.md). The commands below are the intended public flow.
+> [development guide](../contributing/development.md). The commands below are the intended public flow.
 
 ## Requirements
 

init.sh

@@ -133,7 +133,7 @@ command_symlink="/usr/local/bin/libreportal"
 # systemd unit, sudoers). BUMP THIS whenever you change any of those — a plain
 # `update apply` runs as the manager and CANNOT rewrite root-owned files, so a bump
 # tells the updater the new release needs a root re-install (which re-bakes them).
-# Recorded at install in $lp_lib_dir/.footprint_version. See docs/DEVELOPMENT.md.
+# Recorded at install in $lp_lib_dir/.footprint_version. See docs/contributing/development.md.
 footprint_version=3
 footprint_marker="$lp_lib_dir/.footprint_version"
 
@@ -895,7 +895,7 @@ initUsers()
 # op the manager can't modify), and a fixed system-binary set. Excluded:
 # bash/su + tee/cp/chmod/chown/sed/mv/rm/install (each root-equivalent). Also
 # clears legacy broad grants (a NOPASSWD: ALL in the main /etc/sudoers, sudo-group
-# membership). See docs/FOOTPRINT.md.
+# membership). See docs/architecture/system-footprint.md.
 initScopedSudoers()
 {
 	local sudoers_dropin="/etc/sudoers.d/${sudo_user_name}"
@@ -1620,7 +1620,7 @@ completeInitMessage()
 # containers run AS the docker-install user and the rootless daemon is that user's
 # systemd --user service, so stop those BEFORE removing the users. Self-contained:
 # uses only init.sh's inline helpers, so it still works as it deletes /docker.
-# Keep in sync with docs/FOOTPRINT.md.
+# Keep in sync with docs/architecture/system-footprint.md.
 # Discover where THIS box was actually installed — custom installs put the roots
 # anywhere, and a bare `init.sh uninstall` has no LP_*_DIR in scope. The systemd
 # unit is the authoritative baked record (Environment=LP_*_DIR + User=<manager>).
@@ -1731,7 +1731,7 @@ runFullUninstall()
 		fi
 	fi
 
-	# 3. Remove the out-of-/docker footprint (see docs/FOOTPRINT.md).
+	# 3. Remove the out-of-/docker footprint (see docs/architecture/system-footprint.md).
 	rm -f /usr/local/bin/libreportal /usr/local/bin/libreportal-uninstall
 	rm -rf /usr/local/lib/libreportal
 	rm -f "/etc/sudoers.d/$mgr"