droidsembly 0.0.0-stage → 0.4.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leon van Zyl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.it.md

@@ -0,0 +1,184 @@
+# Droidsembly
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rosariomoscato/droidsembly/main/client/public/icons/logo-light.svg" alt="Logo Droidsembly" width="360">
+</p>
+
+**Small droids. Serious software.**
+
+Uno spazio visuale per lo sviluppo software assistito dall'AI: collega i tuoi repository GitHub, coordina gli agenti di coding e segui il lavoro in un ufficio 3D interattivo o in una dashboard adatta al telefono.
+
+[English](https://github.com/rosariomoscato/droidsembly/blob/main/README.md) · **Italiano**
+
+[Codice sorgente](https://github.com/rosariomoscato/droidsembly) · [Segnala un problema](https://github.com/rosariomoscato/droidsembly/issues) · [Documentazione](#documentazione) · [Sostieni il progetto](#sostieni-il-progetto)
+
+**Sito in arrivo:** `droidsembly.com`. Fino alla sua apertura, questo repository è il riferimento per installazione e documentazione.
+
+**Gratuito e open source, con licenza MIT.** Nessuna attivazione a pagamento o sblocco commerciale degli agenti. Il sostegno volontario aiuta lo sviluppo; abbonamenti AI, consumi API e servizi cloud opzionali hanno costi e limiti propri.
+
+## Guarda l'ufficio
+
+![Lobby demo di Droidsembly con agenti robot, reception e uffici del manager e del CEO](https://raw.githubusercontent.com/rosariomoscato/droidsembly/main/docs/branding/screenshots/office.png)
+
+<details>
+<summary>Kanban e vista mobile Pocket</summary>
+
+![Bacheca Kanban demo con backlog, sviluppo, QA e fasi di merge](https://raw.githubusercontent.com/rosariomoscato/droidsembly/main/docs/screenshots/cyan-panels/kanban-en.png)
+
+<img src="https://raw.githubusercontent.com/rosariomoscato/droidsembly/main/docs/branding/screenshots/pocket-mobile.png" alt="Dashboard Pocket in italiano con stato del progetto, chat CEO e navigazione del team" width="360">
+
+</details>
+
+Sono catture demo già disponibili nel fork. Alcuni dettagli grafici precedono gli ultimi aggiornamenti dei popup; nomi di aziende e progetti sono contenuti dimostrativi.
+
+## Cosa puoi fare
+
+- **Coordinare agenti di coding:** Claude Code, Codex e OpenCode V2, con selezione dei modelli e delle varianti di ragionamento supportate. La disponibilità dipende dal runtime: Agent SDK resta esclusivamente Claude e OpenCode è attualmente solo locale.
+- **Seguire il workflow completo:** issue → sviluppo e controlli iniziali → pull request → sessione QA separata → correzioni → merge quando le condizioni configurate sono soddisfatte.
+- **Mantenere il controllo:** assegnazione manuale o automatica, onboarding CEO facoltativo, approvazione dei cambi team e interruttore distinto per il merge automatico.
+- **Osservare il lavoro reale:** terminali live, piani dei progetti, Kanban e console del manager. Clone e worktree locali separano le copie di lavoro degli agenti; non sono sandbox di sicurezza.
+- **Consultare l'utilizzo AI:** osservazioni multi-provider, token/costi comunicati e limiti selettivi dello scheduler. I dati mancanti restano non disponibili, non zero o illimitati. Vedi [Utilizzo AI](https://github.com/rosariomoscato/droidsembly/blob/main/docs/AI_USAGE.md).
+- **Chiedere analisi in sola lettura:** avvia una conversazione senza issue o PR. Le regole di sola lettura sono istruzioni all'agente, non una sandbox.
+- **Usare desktop e mobile:** ufficio 3D e vista Pocket touch, interfaccia inglese/italiana, comandi da tastiera e impostazioni di accessibilità. Vedi [copertura delle lingue](https://github.com/rosariomoscato/droidsembly/blob/main/docs/languages.md).
+- **Personalizzare l'ufficio:** agenti robot, cane robot, decorazioni, musica adattiva, modalità foto e time-lapse.
+
+## Installa questo fork
+
+**Distribuzione attuale: compilazione dai sorgenti.** Il pacchetto npm `droidsembly@0.4.0-beta.1` e il comando pubblico `droidsembly` sono in preparazione locale; non sono stati pubblicati. Non è ancora disponibile un installer desktop. `npx cubefarm` installa il pacchetto originale, non Droidsembly.
+
+Dopo una pubblicazione beta esplicitamente autorizzata, il comando previsto è `npx droidsembly@next` (`npx.cmd droidsembly@next` in PowerShell). Non usarlo finché il rilascio non sarà annunciato in questo repository. Le versioni stabili useranno `latest`; le beta verificano gli aggiornamenti su `next`. Il nuovo pacchetto non espone un alias globale `cubefarm`. Il file interno `bin/cubefarm.js`, i launcher dei checkout esistenti e la cartella dati predefinita restano compatibili.
+
+### Requisiti
+
+- [Node.js](https://nodejs.org/) **22 o successivo**, con npm, e [Git](https://git-scm.com/).
+- Per lavoro reale: [GitHub CLI](https://cli.github.com/), autenticato con `gh auth login`, e un coding agent supportato con accesso al proprio provider.
+- Claude Code è incluso tramite Agent SDK. OpenCode **2.x** e Codex si installano separatamente quando selezionati. Le sessioni terminale esclusivamente OpenCode non richiedono un abbonamento Claude.
+- Google Chrome per gli agenti che verificano i progetti nel browser.
+
+Il progetto è destinato a Windows, macOS e Linux. La demo senza AI descritta sotto non richiede credenziali dei provider o login GitHub.
+
+### 1. Scarica e compila
+
+Esegui questi comandi nella cartella che dovrà contenere un **nuovo** checkout.
+
+**Windows — PowerShell**
+
+```powershell
+git clone https://github.com/rosariomoscato/droidsembly.git
+cd droidsembly
+npm.cmd ci
+npm.cmd run build
+```
+
+**macOS / Linux**
+
+```bash
+git clone https://github.com/rosariomoscato/droidsembly.git
+cd droidsembly
+npm ci
+npm run build
+```
+
+### 2. Prova la demo senza AI
+
+Dal checkout, avvia il server compilato con cartella dati e porte dedicate:
+
+**Windows — PowerShell**
+
+```powershell
+$env:SWARM_HOME = Join-Path $env:LOCALAPPDATA 'Droidsembly-Demo'
+$env:SWARM_PORT = '4419'
+$env:SWARM_HOST = '127.0.0.1'
+$env:SWARM_PREVIEW_PORT = '9600'
+$env:SWARM_DEMO = '1'
+node dist-server/index.js --demo
+```
+
+**macOS / Linux**
+
+```bash
+SWARM_HOME="$HOME/.droidsembly-demo" SWARM_PORT=4419 SWARM_HOST=127.0.0.1 SWARM_PREVIEW_PORT=9600 SWARM_DEMO=1 node dist-server/index.js --demo
+```
+
+Apri **http://127.0.0.1:4419/** e verifica che sia indicata la **MODALITÀ DEMO**. GitHub e agenti sono simulati; lo stato demo viene salvato soltanto nella cartella demo scelta. Ferma il server con `Ctrl+C`. Scegli porte libere se queste sono occupate.
+
+### 3. Avvia un ufficio reale
+
+Ferma prima la demo. Usa una cartella dati distinta e rimuovi `--demo`. Le sessioni reali possono modificare i progetti collegati e consumare quota AI.
+
+**Windows — PowerShell**
+
+```powershell
+$env:SWARM_HOME = Join-Path $env:LOCALAPPDATA 'Droidsembly'
+$env:SWARM_PORT = '4419'
+$env:SWARM_HOST = '127.0.0.1'
+$env:SWARM_PREVIEW_PORT = '9600'
+$env:SWARM_DEMO = '0'
+node dist-server/index.js
+```
+
+**macOS / Linux**
+
+```bash
+SWARM_HOME="$HOME/.droidsembly" SWARM_PORT=4419 SWARM_HOST=127.0.0.1 SWARM_PREVIEW_PORT=9600 SWARM_DEMO=0 node dist-server/index.js
+```
+
+Apri **http://127.0.0.1:4419/**. Le cartelle degli esempi sono una scelta esplicita per una nuova installazione, non una migrazione: percorsi dati e launcher esistenti restano validi. Senza `SWARM_HOME`, il percorso predefinito dell'app rimane `~/.cubefarm`.
+
+Prima di collegare un progetto, seleziona il coding agent del CEO se non vuoi usare il predefinito Claude Code. Per saltare l'analisi AI iniziale, disattiva l'opzione che permette al CEO di studiare il repository e pianificare dal brief. Assegnazione automatica, merge automatico e revisioni periodiche CEO sono impostazioni distinte. Vedi [Agenti](https://github.com/rosariomoscato/droidsembly/blob/main/docs/agents.md) per configurazione dei provider e limiti dei runtime.
+
+## Desktop, mobile e PWA
+
+Il backend Node.js gira sul computer; il browser visualizza e controlla l'ufficio. Installare la PWA aggiunge l'interfaccia alla schermata iniziale, **ma non installa il backend Node.js o i coding agent**. Il computer dell'ufficio deve restare acceso e raggiungibile.
+
+Per installazione mobile e accesso remoto privato, segui [Pocket](https://github.com/rosariomoscato/droidsembly/blob/main/docs/pocket.md) e [Accesso da telefono](https://github.com/rosariomoscato/droidsembly/blob/main/docs/phone-access.md). Le funzioni PWA richiedono un browser compatibile e un contesto sicuro, come HTTPS o localhost. L'ufficio non ha un login integrato: mantienilo su loopback oppure usa un accesso privato autenticato, anziché esporlo pubblicamente.
+
+### Comandi essenziali
+
+| Comando | Azione |
+| --- | --- |
+| `W A S D` / frecce | Cammina |
+| `Shift` | Corri |
+| `E` / clic sinistro | Interagisci |
+| `P` | Apri il telefono |
+| `Tab` | Panoramica dell'ufficio |
+| `K` | Modalità foto |
+| `M` | Silenzia |
+| `H` | Guida e lista completa dei comandi |
+| `Esc` | Libera il mouse / chiudi un pannello |
+
+Le impostazioni comprendono sottotitoli, comfort di movimento, scala UI, contrasto e viste a elenco. Pocket offre navigazione adatta al touch.
+
+## Aggiornamenti
+
+Per un'installazione dai sorgenti, ferma l'ufficio quando gli agenti sono inattivi, salva un backup dello `SWARM_HOME` scelto e consulta il [changelog del fork](https://github.com/rosariomoscato/droidsembly/blob/main/docs/FORK_CHANGELOG.md). In un checkout pulito su `main`, esegui `git pull --ff-only`, poi `npm.cmd ci` e `npm.cmd run build` su Windows (`npm ci` e `npm run build` su macOS/Linux). Riavvia con la stessa cartella dati e le stesse porte. Preserva eventuali modifiche locali prima di aggiornare.
+
+Non usare `npx cubefarm@latest` per aggiornare questo fork: punta al pacchetto npm originale. La CLI preparata verifica soltanto `droidsembly`, su `next` per le prerelease e `latest` per le stabili; una voce del registry non disponibile viene ignorata. I comandi diretti del server qui indicati non usano il launcher autoaggiornante del checkout; vedi [come funzionano gli aggiornamenti](https://github.com/rosariomoscato/droidsembly/blob/main/docs/how-it-works.md#updating-the-office) per quel flusso distinto. Gli aggiornamenti del pacchetto sono manuali; installare un nuovo nome npm non migra un'installazione esistente o i suoi dati.
+
+## Sostieni il progetto
+
+Droidsembly è gratuito e open source. Se ti è utile, puoi sostenerne lo sviluppo lasciando una stella al repository, condividendolo, segnalando problemi riproducibili o contribuendo con miglioramenti.
+
+**È previsto il sostegno economico volontario tramite GitHub Sponsors.** Il profilo non è ancora attivo; il link verrà aggiunto quando disponibile. Nessuna donazione è necessaria per usare l'app o sbloccare gli agenti. Restano applicabili i limiti tecnici e le quote dei provider AI.
+
+## Documentazione
+
+- [Agenti e configurazione dei provider](https://github.com/rosariomoscato/droidsembly/blob/main/docs/agents.md)
+- [Workflow, terminali, QA e aggiornamenti](https://github.com/rosariomoscato/droidsembly/blob/main/docs/how-it-works.md)
+- [Utilizzo AI multi-provider](https://github.com/rosariomoscato/droidsembly/blob/main/docs/AI_USAGE.md) (italiano)
+- [Pocket, PWA e notifiche](https://github.com/rosariomoscato/droidsembly/blob/main/docs/pocket.md) · [Accesso da telefono](https://github.com/rosariomoscato/droidsembly/blob/main/docs/phone-access.md)
+- [Agenti cloud opzionali](https://github.com/rosariomoscato/droidsembly/blob/main/docs/cloud.md) · [Voce](https://github.com/rosariomoscato/droidsembly/blob/main/docs/voice.md)
+- [Copertura inglese/italiano](https://github.com/rosariomoscato/droidsembly/blob/main/docs/languages.md)
+- [Contributi e sviluppo](https://github.com/rosariomoscato/droidsembly/blob/main/CONTRIBUTING.md)
+- [Changelog del fork](https://github.com/rosariomoscato/droidsembly/blob/main/docs/FORK_CHANGELOG.md) (italiano)
+- [Report delle verifiche locali](https://github.com/rosariomoscato/droidsembly/blob/main/docs/validation-english-italian.md) · [Indagine sul pathfinding](https://github.com/rosariomoscato/droidsembly/blob/main/docs/pathfinding-investigation.md)
+
+Parte delle guide tecniche è in inglese. I risultati CI e i fallimenti storici locali sono evidenze distinte: una CI verde non dimostra che quei fallimenti locali siano risolti.
+
+## Crediti e licenza
+
+Droidsembly è mantenuto da [Rosario Moscato](https://github.com/rosariomoscato), a partire da [CubeFarm di Leon van Zyl](https://github.com/leonvanzyl/cubefarm). Questo fork era precedentemente ospitato su `rosariomoscato/cubefarm`.
+
+Il fork aggiunge integrazione OpenCode V2, selezione di modelli/varianti, onboarding facoltativo e analisi manuale, supporto inglese/italiano, grafica robotica e identità visiva, stile coordinato desktop/mobile, musica adattiva e monitoraggio dell'utilizzo multi-provider. Il [changelog](https://github.com/rosariomoscato/droidsembly/blob/main/docs/FORK_CHANGELOG.md) documenta implementazioni e verifiche.
+
+Distribuito con licenza [MIT](https://github.com/rosariomoscato/droidsembly/blob/main/LICENSE), conservando l'avviso originale **Copyright (c) 2026 Leon van Zyl**. I componenti di terze parti mantengono le rispettive licenze, inclusa la [SIL Open Font License del font Sora](https://github.com/rosariomoscato/droidsembly/blob/main/client/public/icons/Sora-OFL.txt).

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Droidsembly
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rosariomoscato/droidsembly/main/client/public/icons/logo-light.svg" alt="Droidsembly logo" width="360">
+</p>
+
+**Small droids. Serious software.**
+
+A visual workspace for AI-assisted software development: connect your GitHub repositories, coordinate coding agents and follow their work in an interactive 3D office or a mobile-friendly dashboard.
+
+**English** · [Italiano](https://github.com/rosariomoscato/droidsembly/blob/main/README.it.md)
+
+[Source code](https://github.com/rosariomoscato/droidsembly) · [Report an issue](https://github.com/rosariomoscato/droidsembly/issues) · [Documentation](#documentation) · [Support the project](#support-the-project)
+
+**Website coming soon:** `droidsembly.com`. Until it launches, this repository is the reference for installation and documentation.
+
+**Free and open source, under the MIT license.** No paid activation or commercial agent unlocks. Voluntary support helps development; your AI subscriptions, API usage and optional cloud services have their own costs and limits.
+
+## See the office
+
+![Droidsembly demo lobby with robot agents, reception and the manager and CEO offices](https://raw.githubusercontent.com/rosariomoscato/droidsembly/main/docs/branding/screenshots/office.png)
+
+<details>
+<summary>Kanban and mobile Pocket view</summary>
+
+![Demo Kanban board showing backlog, development, QA and merge stages](https://raw.githubusercontent.com/rosariomoscato/droidsembly/main/docs/screenshots/cyan-panels/kanban-en.png)
+
+<img src="https://raw.githubusercontent.com/rosariomoscato/droidsembly/main/docs/branding/screenshots/pocket-mobile.png" alt="Italian Pocket dashboard with project status, CEO chat and team navigation" width="360">
+
+</details>
+
+These are existing demo captures from the fork. Some styling predates the latest popup updates; company and project names are demo content.
+
+## What you can do
+
+- **Coordinate coding agents:** Claude Code, Codex and OpenCode V2, with model selection and supported reasoning variants. Provider availability depends on the runtime; the Agent SDK runtime is Claude-only, and OpenCode is currently local-only.
+- **Follow the full workflow:** issue → development and initial checks → pull request → separate QA session → corrections → merge when the configured conditions pass.
+- **Keep control:** manual or automatic assignment, optional CEO onboarding, team-change approvals and a separate auto-merge switch.
+- **Watch real work:** live terminals, project floors, a Kanban board and the manager console. Local clones and worktrees separate agents' working copies; they are not security sandboxes.
+- **Inspect AI usage:** multi-provider observations, reported tokens/costs and selective scheduling limits. Missing provider data remains unavailable, not zero or unlimited. See [AI usage](https://github.com/rosariomoscato/droidsembly/blob/main/docs/AI_USAGE.md) (Italian).
+- **Ask for read-only analysis:** start a discussion without an issue or PR. Read-only rules are agent instructions, not a sandbox.
+- **Use desktop or mobile:** a 3D office and a touch-friendly Pocket view, English/Italian interface, keyboard controls and accessibility settings. See [language coverage](https://github.com/rosariomoscato/droidsembly/blob/main/docs/languages.md).
+- **Make the office yours:** robot agents, a robot dog, decorations, adaptive music, photo mode and time-lapse.
+
+## Install this fork
+
+**Current distribution: build from source.** The npm package `droidsembly@0.4.0-beta.1` and public command `droidsembly` are being prepared locally; they have not been published. There is no desktop installer yet. `npx cubefarm` installs the original package, not Droidsembly.
+
+After an explicitly authorized beta release, the planned command is `npx droidsembly@next` (`npx.cmd droidsembly@next` in PowerShell). Do not use it until the release is announced in this repository. Stable releases will use `latest`; beta versions check `next` for updates. The new package exposes no global `cubefarm` alias. The internal entry file `bin/cubefarm.js`, existing checkout launchers and default data directory remain compatible.
+
+### Requirements
+
+- [Node.js](https://nodejs.org/) **22 or newer**, with npm, and [Git](https://git-scm.com/).
+- For real work: [GitHub CLI](https://cli.github.com/), authenticated with `gh auth login`, and a supported coding agent signed in to its provider.
+- Claude Code is bundled through the Agent SDK. OpenCode **2.x** and Codex are installed separately when selected. OpenCode-only terminal sessions do not require a Claude subscription.
+- Google Chrome for agents that test projects in a browser.
+
+The project targets Windows, macOS and Linux. The no-AI demo below does not require provider credentials or a GitHub login.
+
+### 1. Download and build
+
+Run these commands in the parent folder where you want a **new** checkout.
+
+**Windows — PowerShell**
+
+```powershell
+git clone https://github.com/rosariomoscato/droidsembly.git
+cd droidsembly
+npm.cmd ci
+npm.cmd run build
+```
+
+**macOS / Linux**
+
+```bash
+git clone https://github.com/rosariomoscato/droidsembly.git
+cd droidsembly
+npm ci
+npm run build
+```
+
+### 2. Try the no-AI demo
+
+From the checkout, start the built server with a dedicated data folder and ports:
+
+**Windows — PowerShell**
+
+```powershell
+$env:SWARM_HOME = Join-Path $env:LOCALAPPDATA 'Droidsembly-Demo'
+$env:SWARM_PORT = '4419'
+$env:SWARM_HOST = '127.0.0.1'
+$env:SWARM_PREVIEW_PORT = '9600'
+$env:SWARM_DEMO = '1'
+node dist-server/index.js --demo
+```
+
+**macOS / Linux**
+
+```bash
+SWARM_HOME="$HOME/.droidsembly-demo" SWARM_PORT=4419 SWARM_HOST=127.0.0.1 SWARM_PREVIEW_PORT=9600 SWARM_DEMO=1 node dist-server/index.js --demo
+```
+
+Open **http://127.0.0.1:4419/** and confirm **DEMO MODE** is displayed. GitHub and agents are simulated; demo state is saved only in the chosen demo folder. Stop with `Ctrl+C`. Choose unused ports if these are occupied.
+
+### 3. Start a real office
+
+Stop the demo first. Use a separate data folder and remove `--demo`. Real sessions can modify connected projects and consume AI quota.
+
+**Windows — PowerShell**
+
+```powershell
+$env:SWARM_HOME = Join-Path $env:LOCALAPPDATA 'Droidsembly'
+$env:SWARM_PORT = '4419'
+$env:SWARM_HOST = '127.0.0.1'
+$env:SWARM_PREVIEW_PORT = '9600'
+$env:SWARM_DEMO = '0'
+node dist-server/index.js
+```
+
+**macOS / Linux**
+
+```bash
+SWARM_HOME="$HOME/.droidsembly" SWARM_PORT=4419 SWARM_HOST=127.0.0.1 SWARM_PREVIEW_PORT=9600 SWARM_DEMO=0 node dist-server/index.js
+```
+
+Open **http://127.0.0.1:4419/**. These example folders are an explicit choice for a new installation, not a migration: existing data paths and launchers remain valid. Without `SWARM_HOME`, the application's default remains `~/.cubefarm`.
+
+Before connecting a project, select the CEO's coding agent if you do not want the default Claude Code. To skip the initial AI analysis, turn off **Let the CEO study this repository and plan from the brief**. Auto-assignment, auto-merge and periodic CEO reviews are separate settings. See [Agents](https://github.com/rosariomoscato/droidsembly/blob/main/docs/agents.md) for provider setup and runtime limitations.
+
+## Desktop, mobile and PWA
+
+The Node.js backend runs on your computer; the browser displays and controls the office. Installing the PWA adds the interface to your home screen **but does not install the Node.js backend or coding agents**. The office computer must remain running and reachable.
+
+For mobile installation and private remote access, follow [Pocket mode](https://github.com/rosariomoscato/droidsembly/blob/main/docs/pocket.md) and [Phone access](https://github.com/rosariomoscato/droidsembly/blob/main/docs/phone-access.md). PWA features require a supported browser and a secure context, such as HTTPS or localhost. The office has no built-in sign-in: keep it on loopback or use authenticated private access rather than exposing it publicly.
+
+### Essential controls
+
+| Control | Action |
+| --- | --- |
+| `W A S D` / arrows | Walk |
+| `Shift` | Run |
+| `E` / left click | Interact |
+| `P` | Open the phone |
+| `Tab` | Office overview |
+| `K` | Photo mode |
+| `M` | Mute |
+| `H` | Help and full control list |
+| `Esc` | Release the mouse / close a panel |
+
+Settings include captions, motion comfort, UI scaling, contrast and list views. Pocket provides touch-friendly navigation.
+
+## Updating
+
+For a source installation, stop the office when agents are idle, back up your chosen `SWARM_HOME`, and review the [fork changelog](https://github.com/rosariomoscato/droidsembly/blob/main/docs/FORK_CHANGELOG.md). In a clean checkout on `main`, use `git pull --ff-only`, then `npm.cmd ci` and `npm.cmd run build` on Windows (`npm ci` and `npm run build` on macOS/Linux). Restart using the same data folder and ports. Preserve local changes before updating.
+
+Do not use `npx cubefarm@latest` to update this fork: it targets the original npm package. This prepared CLI checks only `droidsembly`, using `next` for prereleases and `latest` for stable versions; an unavailable registry entry is ignored. The direct server commands above do not use the checkout's self-updating launcher; see [how updating works](https://github.com/rosariomoscato/droidsembly/blob/main/docs/how-it-works.md#updating-the-office) for that separate workflow. Package updates are manual; installing a new package name does not migrate an existing installation or its data.
+
+## Support the project
+
+Droidsembly is free and open source. If it helps you, you can support its development by starring the repository, sharing it, reporting reproducible issues or contributing improvements.
+
+**Voluntary financial support is planned through GitHub Sponsors.** The profile is not yet activated; a link will be added when it is available. No donation is required to use the app or unlock agents. Technical limits and AI-provider quotas still apply.
+
+## Documentation
+
+- [Agents and provider setup](https://github.com/rosariomoscato/droidsembly/blob/main/docs/agents.md)
+- [Workflow, terminals, QA and updates](https://github.com/rosariomoscato/droidsembly/blob/main/docs/how-it-works.md)
+- [Multi-provider AI usage](https://github.com/rosariomoscato/droidsembly/blob/main/docs/AI_USAGE.md) (Italian)
+- [Pocket, PWA and notifications](https://github.com/rosariomoscato/droidsembly/blob/main/docs/pocket.md) · [Phone access](https://github.com/rosariomoscato/droidsembly/blob/main/docs/phone-access.md)
+- [Optional cloud agents](https://github.com/rosariomoscato/droidsembly/blob/main/docs/cloud.md) · [Voice](https://github.com/rosariomoscato/droidsembly/blob/main/docs/voice.md)
+- [English/Italian coverage](https://github.com/rosariomoscato/droidsembly/blob/main/docs/languages.md)
+- [Contributing and development](https://github.com/rosariomoscato/droidsembly/blob/main/CONTRIBUTING.md)
+- [Fork changelog](https://github.com/rosariomoscato/droidsembly/blob/main/docs/FORK_CHANGELOG.md) (Italian)
+- [Local validation report](https://github.com/rosariomoscato/droidsembly/blob/main/docs/validation-english-italian.md) · [Pathfinding investigation](https://github.com/rosariomoscato/droidsembly/blob/main/docs/pathfinding-investigation.md)
+
+CI results and historical local test failures are separate evidence; a green CI run does not establish that those local failures have been resolved.
+
+## Credits and license
+
+Droidsembly is maintained by [Rosario Moscato](https://github.com/rosariomoscato), based on [CubeFarm by Leon van Zyl](https://github.com/leonvanzyl/cubefarm). This fork was previously hosted at `rosariomoscato/cubefarm`.
+
+The fork adds OpenCode V2 integration, model/variant selection, optional onboarding and manual analysis, English/Italian support, robot visuals and branding, coordinated desktop/mobile styling, adaptive music and multi-provider usage monitoring. The [changelog](https://github.com/rosariomoscato/droidsembly/blob/main/docs/FORK_CHANGELOG.md) records implementation and validation history.
+
+Licensed under [MIT](https://github.com/rosariomoscato/droidsembly/blob/main/LICENSE), preserving the original **Copyright (c) 2026 Leon van Zyl** notice. Third-party components retain their respective licenses, including the [Sora font's SIL Open Font License](https://github.com/rosariomoscato/droidsembly/blob/main/client/public/icons/Sora-OFL.txt).