@webship.co/workspace 0.0.0-stage → 1.0.0-alpha1

package/ddev.js

@@ -0,0 +1,145 @@
+const fs = require('fs');
+const path = require('path');
+/**
+ * The DDEV verbs a row's menu offers, as a table rather than as six near-identical branches.
+ *
+ * `needsRunning` is refused rather than attempted: `ddev drush` on a stopped project produces a
+ * wall of connection errors instead of a sentence. `toBackups` writes into the workspace's backups
+ * directory, so an export lands where the restore button looks for it.
+ */
+
+/**
+ * ONE `ddev start` at a time, machine-wide.
+ *
+ * Every router-mutating verb (`start`, `stop`, `restart`, `poweroff`, `delete`) tears the
+ * SHARED `ddev-router` down and brings it back up with the routes of whatever is running.
+ * Run two at once and they race on one container: one removes it while the other has just
+ * created it, and the loser can leave it removed for good. What that looks like is the whole
+ * workspace going dark — every *.ddev.site address, the dashboard's own hub included, with
+ * healthy web containers behind it and DDEV then refusing to start anything at all:
+ *
+ *   Failed to start workspace: Error response from daemon: No such container: ddev-router
+ *
+ * Recovering needs `ddev poweroff`. It is easy to trigger: five clicks on Start in
+ * thirty-eight seconds did it here, because each one is its own detached screen session.
+ *
+ * `flock` and not an in-process queue: the dashboard is not the only door. A person at a
+ * terminal, an agent, and a cmd-*.sh script all run `ddev` too, and a lock in this process
+ * would not be seen by any of them. The lock file lives at the root of the workspace tree,
+ * which is bind-mounted at the SAME absolute path inside the container — so the host and the
+ * dashboard take the same lock.
+ *
+ * The command runs EXACTLY ONCE. The obvious shape — `flock -n … cmd || flock -w … cmd` —
+ * is wrong: `||` fires on any non-zero exit, so a start that failed on its own merits would
+ * be run a second time. So the lock is probed with `true` purely to decide whether to say
+ * "waiting", and the real call is a single bounded acquire whose status is the session's.
+ *
+ * NO SHELL VARIABLES IN HERE. The line travels through two shells — the runner builds
+ * `bash -lc "… screen -dmS <s> bash -lc \"<this>\" …"` — so the OUTER one expands anything
+ * starting with `$` before the inner one ever sees it. A first version captured `rc=$?` and
+ * tested it, and the session logged `[: : integer expected` because `$rc` had already been
+ * expanded away to nothing by the outer shell. Keeping the string free of `$` makes it
+ * immune to however many quoting layers it passes through.
+ */
+const ROUTER_VERBS = new Set(['start', 'stop', 'restart', 'poweroff', 'delete']);
+
+function routerLockPath() {
+  const { ROOT } = require('./workspaces');
+  return path.join(ROOT, '.ddev-router.lock');
+}
+
+/** Wrap a command line so it holds the router lock while it runs. */
+function serialiseRouter(cmdLine) {
+  const lock = JSON.stringify(routerLockPath());
+  const busy = 'Waiting: another ddev start/stop/restart holds the router lock. '
+    + 'They cannot run at once — each one recreates the shared ddev-router.';
+  // The probe cannot fail the session: `|| echo` only decides whether to explain the wait.
+  // The second flock is the last command, so ITS status is the session's status.
+  // DDEV_ROUTER_LOCK_HELD tells the `ddev` shim (core/scripts/ddev-shim/ddev, on PATH in
+  // this container) that the lock is ALREADY held by this very command, so it runs instead
+  // of taking the same lock again. Without it the two protections deadlock each other:
+  // proven — an outer flock plus an unaware shim hangs for the full 1800s timeout.
+  return `{ flock -n ${lock} true || echo ${JSON.stringify(busy)} ; } ; `
+    + `flock -w 1800 ${lock} env DDEV_ROUTER_LOCK_HELD=1 ${cmdLine}`;
+}
+
+/** Does this argv touch the router? */
+function touchesRouter(args) { return ROUTER_VERBS.has(String((args || [])[0] || '')); }
+
+const DDEV_ACTIONS = {
+  '/actions/ddev-restart':   { icon: '🔄', label: 'ddev restart',       args: ['restart'],                            ms: 5 * 60 * 1000 },
+  '/actions/ddev-describe':  { icon: 'ℹ️',  label: 'ddev describe',      args: ['describe'],                           ms: 60 * 1000 },
+  '/actions/ddev-logs':      { icon: '📜', label: 'ddev logs',          args: ['logs', '-s', 'web', '--tail', '100'], ms: 60 * 1000 },
+  '/actions/ddev-drush-cr':  { icon: '⚡', label: 'ddev drush cr',      args: ['drush', 'cr'],                        ms: 5 * 60 * 1000, needsRunning: true },
+  '/actions/ddev-drush-uli': { icon: '🔑', label: 'ddev drush uli',     args: ['drush', 'uli'],                       ms: 60 * 1000, needsRunning: true },
+  '/actions/ddev-export-db': { icon: '💾', label: 'ddev export-db',     args: ['export-db'],                          ms: 10 * 60 * 1000, needsRunning: true, toBackups: true },
+  // Long ones run detached in a screen session: a composer update outlives any
+  // page, and it must be watchable and reattachable rather than tied to a toast.
+  '/actions/ddev-composer-install': { icon: '📦', label: 'ddev composer install', args: ['composer', 'install'],            ms: 60 * 60 * 1000, inScreen: true },
+  '/actions/ddev-composer-update':  { icon: '⬆️',  label: 'ddev composer update',  args: ['composer', 'update'],             ms: 60 * 60 * 1000, inScreen: true },
+  '/actions/ddev-drush-updb':       { icon: '🗃️',  label: 'ddev drush updb',       args: ['drush', 'updb', '-y'],            ms: 30 * 60 * 1000, needsRunning: true, inScreen: true },
+  '/actions/ddev-drush-cim':        { icon: '📥', label: 'ddev drush cim',        args: ['drush', 'cim', '-y'],             ms: 30 * 60 * 1000, needsRunning: true, inScreen: true },
+  '/actions/ddev-drush-cex':        { icon: '📤', label: 'ddev drush cex',        args: ['drush', 'cex', '-y'],             ms: 30 * 60 * 1000, needsRunning: true, inScreen: true },
+  '/actions/ddev-drush-status':     { icon: '🩺', label: 'ddev drush status',     args: ['drush', 'status'],                ms: 2 * 60 * 1000, needsRunning: true },
+  // A snapshot can be named, and one that is not gets DDEV's timestamp. `needsRunning` is honest
+  // rather than strict: `ddev snapshot` will START a stopped project to take one and stop it again,
+  // which is a surprise worth not springing on somebody who clicked a menu item.
+  '/actions/ddev-snapshot':         { icon: '📸', label: 'ddev snapshot',         args: ['snapshot'],                       ms: 15 * 60 * 1000, needsRunning: true, named: true },
+  // Restoring REPLACES the database — there is no merge and no undo, which is why it is confirmed
+  // and why it runs in a screen: a large database takes minutes and must be watchable.
+  '/actions/ddev-snapshot-restore': { icon: '⏮️',  label: 'ddev snapshot restore', args: ['snapshot', 'restore'],            ms: 30 * 60 * 1000, destructive: true, inScreen: true, named: true },
+  // Removing one is `--cleanup --name <n> -y`; it takes the same confirm, because a snapshot is
+  // somebody's only copy of a database often enough.
+  '/actions/ddev-snapshot-delete':  { icon: '🗑️',  label: 'ddev snapshot cleanup', args: ['snapshot', '--cleanup', '-y'],    ms: 5 * 60 * 1000, destructive: true, named: true },
+  '/actions/ddev-mutagen-sync':     { icon: '🔃', label: 'ddev mutagen sync',     args: ['mutagen', 'sync'],                ms: 10 * 60 * 1000 },
+  // Step debugging, on and off. It is a toggle in the web container rather than a config change, so
+  // it costs nothing and needs no restart — which is exactly why it belongs on a menu instead of in
+  // somebody's shell history. Xdebug makes PHP roughly three times slower while it is on, so turning
+  // it OFF is the half people forget, and the menu says which state it is in before either is clicked.
+  '/actions/ddev-xdebug-on':        { icon: '🐞', label: 'ddev xdebug on',        args: ['xdebug', 'on'],                   ms: 2 * 60 * 1000, needsRunning: true },
+  '/actions/ddev-xdebug-off':       { icon: '🐞', label: 'ddev xdebug off',       args: ['xdebug', 'off'],                  ms: 2 * 60 * 1000, needsRunning: true },
+  // Which it is now. `ddev describe` does not report it — checked — so a row cannot show the state
+  // without a subprocess of its own, and asking is a click rather than a cost on every render.
+  '/actions/ddev-xdebug-status':    { icon: '🐞', label: 'ddev xdebug status',    args: ['xdebug', 'status'],               ms: 60 * 1000, needsRunning: true },
+  // Your SSH keys, into the container that lends them to every project. It is what makes a composer
+  // install against a private repository work, and it is INTERACTIVE — ssh-add asks for the
+  // passphrase — so it runs in a screen session you can open and type into. Nothing else here needs
+  // a human at the keyboard, which is exactly why it would be baffling as a fire-and-forget button.
+  '/actions/ddev-auth-ssh':         { icon: '🔑', label: 'ddev auth ssh',         args: ['auth', 'ssh'],                    ms: 10 * 60 * 1000, inScreen: true },
+  // A public tunnel to this project, for showing somebody the work. It RUNS UNTIL IT IS STOPPED and
+  // it puts a local site on the open internet, so: a screen session (the URL it prints is in there,
+  // and closing a browser tab must not take the tunnel down with it), and the confirm dialog — this
+  // is the only verb here whose effect is visible to people who are not on this machine.
+  '/actions/ddev-share':            { icon: '🌍', label: 'ddev share',            args: ['share'],                          ms: 8 * 60 * 60 * 1000, needsRunning: true, destructive: true, inScreen: true,
+    confirmWhy: 'puts this project on the open internet' },
+  // When a project is broken, these are the four questions worth asking before anyone starts
+  // guessing — Docker and the network, the certificate, the ports, and whether the database volume
+  // is the version the config claims. Each reads and reports; none of them changes anything, which
+  // is why they are one group and why none is confirmed.
+  '/actions/ddev-diagnose':         { icon: '🩺', label: 'ddev utility diagnose',        args: ['utility', 'diagnose'],        ms: 5 * 60 * 1000 },
+  '/actions/ddev-tls-diagnose':     { icon: '🔏', label: 'ddev utility tls-diagnose',    args: ['utility', 'tls-diagnose'],    ms: 5 * 60 * 1000 },
+  '/actions/ddev-port-diagnose':    { icon: '🔌', label: 'ddev utility port-diagnose',   args: ['utility', 'port-diagnose'],   ms: 5 * 60 * 1000 },
+  // The one that answers "it started, and then the database was empty / the wrong version": the
+  // volume on disk against what config.yaml says it should be.
+  '/actions/ddev-db-match':         { icon: '🗄️',  label: 'ddev utility check-db-match',  args: ['utility', 'check-db-match'],  ms: 2 * 60 * 1000 },
+  // Mutagen beyond `sync`. Status answers the question a slow or stale project raises — is the sync
+  // behind, or is it broken — and it says plainly when Mutagen is not enabled at all, which is worth
+  // knowing before anybody blames it.
+  '/actions/ddev-mutagen-status':   { icon: '🔃', label: 'ddev mutagen status',   args: ['mutagen', 'status'],              ms: 2 * 60 * 1000 },
+  // Reset STOPS THE PROJECT and removes the sync volume, which is why it is confirmed: it is the
+  // answer to a sync that cannot be repaired, and it is not a thing to click while somebody is
+  // working. The files on disk are the source; the volume is rebuilt on the next start.
+  '/actions/ddev-mutagen-reset':    { icon: '♻️',  label: 'ddev mutagen reset',    args: ['mutagen', 'reset'],               ms: 10 * 60 * 1000, destructive: true,
+    confirmWhy: 'stops the project and removes its sync volume' },
+  // Destructive: every table goes. It takes a dump into the workspace's backups
+  // folder first, because there is nothing else keeping that database.
+  '/actions/ddev-drush-sql-drop':   { icon: '🧨', label: 'ddev drush sql:drop',   args: ['drush', 'sql:drop', '-y'],        ms: 10 * 60 * 1000, needsRunning: true, destructive: true, backupFirst: true },
+};
+
+// The project's OWN ddev commands, from every .ddev/commands/<service>/ folder. See ddev-custom-commands.js.
+function projectDdevCommands(projectDir) {
+  return require('./ddev-custom-commands').customCommands(projectDir).map((c) => ({ ...c, help: c.description }));
+}
+
+module.exports = { DDEV_ACTIONS, projectDdevCommands,
+  serialiseRouter, touchesRouter, routerLockPath, ROUTER_VERBS };

package/docs/DEVELOPER-GUIDE.md

@@ -0,0 +1,224 @@
+# Developer guide
+
+For changing the tooling itself: adding a command, a builder, a workspace, or a dashboard feature.
+If you only want to *use* the workspace, [USER-GUIDE.md](USER-GUIDE.md) is the one you want.
+
+Everything here is enforced somewhere — by `cmd-smoke-test.sh`, by a unit test, or by a failure that
+has actually happened on a real machine. Where a rule exists because something broke, it says so.
+
+---
+
+## The shape of it
+
+```
+~/workspace/
+├── core/
+│   ├── scripts/            the whole build chain, shared by every command
+│   │   ├── bootstrap.sh              locates the workspace from its own path
+│   │   ├── bootstrap-libraries.sh    argparse, YAML, progress bar
+│   │   ├── bootstrap-functions.sh    an explicit source list — NOT a glob
+│   │   ├── args/arg-*.sh             one argument surface per command family
+│   │   ├── functions/fun-*.sh        where the work actually happens
+│   │   └── tests/cmd-smoke-test.sh   the test suite for the commands
+│   ├── config/
+│   │   ├── settings.yml              the registry: workspaces, secrets, style
+│   │   └── workspace.<name>.settings.yml   one per workspace
+│   └── workspace-app/      the dashboard (node:http + HTMX, no framework)
+└── <workspace>/            dev, test, products, … each with its own cmd-*.sh
+```
+
+**A fresh clone works with no setup.** Every `cmd-*.sh` resolves `WORKSPACE_SCRIPTS` from its own
+`${BASH_SOURCE[0]}` before sourcing `bootstrap.sh`, which derives `WORKSPACE_PATH`, `_ROOT` and
+`_CONFIG` from itself. There is no installer step for this and no `.bashrc` edit; exported
+`WORKSPACE_*` values still win, which is how the dashboard container points at its bind-mounted tree.
+
+---
+
+## Hard rules
+
+These are not style preferences. Each one has cost somebody a rebuild or an outage.
+
+| | |
+| --- | --- |
+| **DDEV only** | `ddev composer`, `ddev drush`, `ddev delete -y -O`, `ddev export-db`. Never host composer, drush or mysql |
+| **Never write a `$databases` block into `settings.php`** | DDEV's `settings.ddev.php` owns it. `set_default_settings` only ensures the config sync directory |
+| **`ddev start` takes `-y`; `ddev stop` does not** | |
+| **Every `cmd-*-project.sh` carries `# workspace-name: <Human Name>`** | the smoke test enforces it and the Build dropdown shows it |
+| **Spawned commands must close stdin** | `stdio: ['ignore','pipe','pipe']` — `ddev`'s `docker exec -i` hangs for ever on an open stdin pipe |
+| **`--help` is only safe on argparse scripts** | never "test" a non-argparse `cmd-*.sh` by running it |
+| **Never hardcode a person** | `contributor.name`/`.email` in `settings.yml`. A shared tool that names one author makes everyone else's commits claim someone else's work |
+
+**A DDEV project does not come back by itself.** Its containers carry `restart: no`, so after a reboot
+every workspace URL answers 404 from a router with nothing behind it. `core/scripts/autostart.sh
+--enable` installs the systemd user service that fixes it. Do **not** reach for a Docker
+`restart: unless-stopped` policy instead: DDEV re-pushes router config on `ddev start`, so a container
+resurrected behind its back comes up with no route and answers nothing — the same 404, harder to find.
+
+**Every router-mutating verb serialises.** `start`, `stop`, `restart`, `poweroff` and `delete` each
+tear down and recreate the one shared `ddev-router`; two at once can leave it destroyed, which takes
+every `*.ddev.site` address down — the dashboard included — while the web containers sit there
+healthy. `core/scripts/ddev-shim/ddev` holds an `flock` for every caller, and `DDEV_ROUTER_LOCK_HELD`
+stops a lock being taken twice by nested callers.
+
+---
+
+## Adding a command
+
+A `cmd-*.sh` is a thin declaration; the work lives in `core/`.
+
+```bash
+#!/usr/bin/env bash
+# workspace-name: My Thing
+
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.dev.settings.yml);
+
+ARGPARSE_DESCRIPTION="What it does, in one line"
+source ${WORKSPACE_SCRIPTS}/args/arg-my-thing.sh || exit 1 ;
+
+shift $#;
+cd ${WORKSPACE_ROOT}/${doc_name};
+my_thing_command ;
+```
+
+Then `args/arg-my-thing.sh` (an `argparse` heredoc) and `functions/fun-my-thing.sh`.
+
+**Add the function file to `bootstrap-functions.sh`.** It is an explicit `source` list, not a glob, so
+a new `fun-*.sh` stays invisible until it is listed there — and the failure is a "command not found"
+a long way from the cause.
+
+Three argparse traps, each found by hitting it:
+
+- **`store_true` yields the string `yes`**, so test `[ "${FLAG}" == 'yes' ]`.
+- **The dest becomes a shell variable**, so avoid names bash already owns. `--hostname` would clobber
+  `$HOSTNAME`; the clone command uses `--extra-hostname` for exactly that reason.
+- **Several `store_const` aliases sharing one dest overwrite each other.** Use one option with a value
+  (`-a start|stop|status`) instead.
+
+Read a flag that a caller may not set as `${FLAG:-}`: `remove_project` is called from the dashboard
+and from other scripts that know nothing about `--force`.
+
+---
+
+## Adding a builder
+
+A builder declares five distribution facts **inline** and lets `build_distribution` do the rest:
+
+```bash
+site_version="~11.0.0"
+distribution_name="webship"
+distribution_title="Webship 11"
+distribution_webroot="docroot"
+distribution_profile_repo="..."
+distribution_project_template="drupal/webship_project"
+```
+
+There is no `core/config/distributions/` — a builder is readable on its own, and changing what one
+builds touches only that file.
+
+**Version strings follow the file name.** `cmd-<distro><major>-<minor>-0-project.sh` pins
+`site_version="~<major>.<minor>.0"` — the three-segment form, so it means "that minor, latest patch".
+A `-x-` builder tracks the branch (`11.0.x-dev`); latest-per-major builders use a caret (`^11`, `^2`).
+
+A whole new distribution is one `args/arg-<name>.sh`, one `functions/fun-distribution-<name>.sh`
+(with `install_<name>_with_drush`, `enable_<name>_extra_components`, `set_<name>_users`) and the
+`cmd-*-project.sh` files that pick versions.
+
+---
+
+## Adding a workspace
+
+Two entries and a directory:
+
+1. the name in the `workspaces:` list in `core/config/settings.yml` — that list is also the home
+   page's card order;
+2. `core/config/workspace.<name>.settings.yml`, holding `doc_name` and optionally
+   `presentation: icon:`/`subtitle:`.
+
+The dashboard re-reads config on a 2-second memo, so there is no restart and no code change. Settings
+→ the `workspaces:` list does all of it from the browser, including the folder and the DDEV hostname
+(which needs a `ddev restart` to resolve — the response says so).
+
+**Deleting one** goes through the same list, and only for a workspace nothing uses (`workspace-delete.js`):
+no item in its folder but its own tooling, no backups, no screen session running there, and not the last
+workspace. It asks three times (the confirm dialog, the name typed, `YES` typed), checks again on the
+server, and removes the list entry, the settings file, the tooling and the folder, and the DDEV hostname.
+Test it on a throwaway `zz-*` workspace, never on one you use.
+
+**Icons are Tabler**, referenced as `tabler:<name>` and parsed out of the vendored sprite, so a name
+that does not exist is refused rather than rendering an empty box.
+
+---
+
+## The dashboard
+
+`server.js` (single file, no framework) + `workspaces.js` (the config bridge) + `public/`.
+Server-rendered HTML fragments, swapped by HTMX.
+
+- **`workspaces.js` reads the config live.** The only hardcoded table is `PRESENTATION`; script
+  discovery is by filename regex, not a hand-maintained map.
+- **Jobs are an in-memory `Map`**, so **do not restart the app while jobs are running** — running
+  builds get orphaned. Build jobs get a 60-minute timeout: a cold-cache `composer create-project` can
+  exceed fifteen.
+- **Every action shells out to the real `cmd-*.sh`.** The button and the command line cannot drift,
+  and the collision checks, refusals and guards live in one place — the script.
+- **The stylesheet is assembled** from `public/css/base.css` + `public/css/components/*.css` + a theme.
+  `public/style.css` is not the source; editing it changes nothing. `cssVersion()` stamps the URL from
+  the parts' mtimes, so a cached browser picks changes up.
+
+Four things that have taken the app down or hidden a feature:
+
+| | |
+| --- | --- |
+| **a backtick inside a template literal** | ends the literal and takes the whole app down with a `SyntaxError` hundreds of lines away. There is a test asserting no HTML comment in these files contains one |
+| **a variable defined in the wrong IIFE** | renders as *nothing at all* — page rendering swallows errors, so a whole action group silently disappeared |
+| **HTMX only swaps 2xx by default** | every 4xx this app returns used to be discarded silently, so a refused save looked like a broken button. `htmx:beforeSwap` in `ui.js` sets `shouldSwap` for 4xx/5xx |
+| **UIkit closes a dropdown on an outside click only** | opening a modal is not one, so the menu stayed open on top of the dialog it had just opened |
+
+---
+
+## Testing
+
+```bash
+bash core/scripts/tests/cmd-smoke-test.sh    # every cmd-*.sh: syntax, bootstrap chain, header
+cd core/workspace-app && npm run test:unit   # node --test
+cd core/workspace-app && npm test            # unit + the cucumber browser suite
+```
+
+The smoke test's exit code is the number of failures, and it needs no environment setup.
+
+**A test that needs machine state skips with the reason**, at run time, rather than failing or being
+excluded — see `tests/step-definitions/preconditions.steps.js`. A suite with permanent red in it stops
+being read, which is how this one drifted for weeks without anyone noticing it could not even launch a
+browser. (In cucumber that is `return 'skipped'`; `this.skip()` is Mocha's and does nothing here.)
+
+---
+
+## Shipping a change
+
+1. **An issue first**, then a PR referencing it. Both end with the Checkpoints checklist; never tick
+   the human-review box.
+2. Work in the git clone at `~/workspace/products/workspace` (branch `1.0.x`), not in the live tree.
+3. After a merge, bring it back with `bash ~/workspace/core/scripts/sync-tooling.sh --pull` — it
+   mirrors the scripts, the dashboard and each workspace's commands, prunes what the clone dropped,
+   re-applies this machine's docker GID, and runs the smoke test.
+4. A release is an annotated tag on `1.0.x` plus a GitHub release titled with the tag. There is no
+   version-bump commit; the installed version is a per-machine stamp, not a committed file.
+
+**Never commit** real credentials, API keys, machine paths or project names. The published files are
+team-installable templates: `CHANGE_ME` and `sk-change-this` are what ship.
+
+---
+
+## Where the rest is
+
+| | |
+| --- | --- |
+| the dashboard screen by screen, with pictures | [README.md](README.md) |
+| using it | [USER-GUIDE.md](USER-GUIDE.md) |
+| every command and flag, and how to install | `README.md` at the top of the repository |
+| the distilled rules and traps | `docs/workspace-tips-and-rules.md` |
+| the dashboard's internals and DDEV wiring | `core/workspace-app/README.md` |
+| what changed and what was learned, dated | `worklogs/` |

package/docs/README.md

@@ -0,0 +1,252 @@
+# Webship Workspace documentation
+
+Three documents, and this is the index.
+
+| | |
+| --- | --- |
+| **[USER-GUIDE.md](USER-GUIDE.md)** | using the workspace: day one, the things you will actually do, and what to try when something is wrong. This is also the **Help** page in the dashboard |
+| **[DEVELOPER-GUIDE.md](DEVELOPER-GUIDE.md)** | changing the tooling: adding a command, a builder, a workspace or a dashboard feature, and the rules that exist because something broke |
+| **this file** | the dashboard screen by screen, with pictures — the long way round |
+
+Beyond these three: `README.md` at the top of the repository is the full reference (every command,
+every flag, how to install), `docs/workspace-tips-and-rules.md` is the distilled rules,
+`core/workspace-app/README.md` is the dashboard's internals, and `worklogs/` is what changed, dated.
+
+Every screenshot here is of a real machine. If the interface you have does not match one, the
+screenshot is the thing that is out of date — say so.
+
+---
+
+## The home page
+
+![The home page](screenshots/guide-home.png)
+
+Every folder in `~/workspace` is a **workspace** with a card. The count under each is real — projects
+on disk, videos, agents — and **BUILDABLE** means that folder carries builders, so a project can be
+created there.
+
+Three parts of the frame are on every page:
+
+| | |
+| --- | --- |
+| **the assistant**, left | the **AI Assistant** on every page, scoped to the one you are on: on `/dev` it knows dev's projects, commands and rules. It can actually run things. Rename it, per workspace or for the whole dashboard, with `assistant: name:` |
+| **the actions rail**, right | collapsed to icons by default, because a project table wants the width. It never disappears, so "what can I do here" is always in the same place |
+| **the version**, in the toolbar | beside the product name. `version unknown` means the tree was installed a way that recorded none — the tooltip lists the commands that set it |
+
+Each card carries **Edit** (its icon and description, in a window over the page) and **Settings** (its
+own settings file, with the other files as tabs) in its corner:
+
+![Edit the Dev card](screenshots/home/edit-card.png)
+
+**Drag a card** to reorder: it lifts and follows the pointer, the others slide aside, the page scrolls at
+its edges, and the order is saved when you let go (Escape puts it back; Alt with an arrow key moves the
+focused card). The order is the `workspaces:` list in `core/config/settings.yml`, which drags the same
+way in Settings. The icons come from each workspace's own settings file.
+
+![Dragging a card](screenshots/home/drag-reorder.png)
+
+---
+
+## A workspace page
+
+![A workspace page](screenshots/guide-workspace-page.png)
+
+**What would you like to create?** at the top (a builder and a name, or **New folder**), then the
+projects. **Build** runs in the background in a screen session — close the tab if you like, it keeps
+going. **Start AI** under it starts Claude Code in the new project once the build succeeds.
+
+![Start AI after the build](screenshots/create-card/start-ai.png)
+
+The state on each card (Running, Stopped, Paused) is also the switch: click it to start or stop the
+project.
+
+Each row carries the project's state and its addresses. A project has two that always work:
+
+- `https://<project>.ddev.site` — the canonical one DDEV gives it
+- `https://<project>.<workspace>.workspace.ddev.site` — the hierarchical one the dashboard hands out
+
+and can be given more (see [Domains](#domains-what-a-project-answers-at)).
+
+The captions under the buttons are status, not decoration: `22 commands`, `not linked`, `no test
+report yet`, `offline`, `none`. They are what tells you whether pressing the button will do anything.
+
+---
+
+## The DDEV menu
+
+![The DDEV menu](screenshots/guide-ddev-menu.png)
+
+Everything DDEV can do to one project, grouped: start and stop, the build (composer), drush, the
+database, and the project itself. Each entry runs the real command in a screen session and streams the
+output — there is nothing here you could not type, which is the point: the button and the command line
+cannot drift.
+
+What the project defines itself is there too, each in its own folding group: its **custom commands**
+(`.ddev/commands/`), its **composer.json scripts** and its **package.json scripts**.
+
+![A project's custom DDEV commands](screenshots/projects/ddev-custom-commands.png)
+
+**Destructive entries ask before they fire.** Drop the database opens the confirm dialog. Remove names
+what goes, offers a database backup first, and keeps its button off until the project's name is typed.
+
+---
+
+## Cloning: a copy, or a branch
+
+![The clone form](screenshots/guide-clone-worktree-off.png)
+
+**Clone** makes a second working project from an existing one, and the form asks which of the two
+things you mean.
+
+A **copy** (the default) copies the files and sends the database through a dump. The two share
+nothing and can diverge for ever. Right when they are two different sites.
+
+A **git worktree** is offered only when the project is a git checkout, labelled with the branch that
+checkout is on:
+
+![The worktree option](screenshots/guide-clone-worktree-on.png)
+
+One shared `.git` and one history, a branch per folder — and still its own DDEV project with its own
+containers and its own database. Right when they are two *branches of one piece of work*: somebody's
+merge request running beside your own build, without a second copy of a repository whose history is
+often larger than the checkout.
+
+The branch field appears only once the option is ticked. It defaults to the clone name, and the branch
+is created from the current HEAD if it does not exist yet.
+
+Three things it does for you, each of which is a mistake people make by hand:
+
+1. **The folder names the project.** The `name:` key is removed from the worktree's
+   `.ddev/config.yaml`, so the directory decides — leave it and the worktree collides with its source.
+2. **The database is never shared.** Two DDEV projects on one database corrupts on the first
+   `drush updatedb`.
+3. **The build is copied.** `vendor/`, contrib, the files directory and `settings.local.php` are
+   git-ignored, so a bare worktree is a source tree and not a running site.
+
+Rows say which is which, so a listing shows what belongs to what:
+
+![Rows showing a worktree and its main checkout](screenshots/guide-rows-worktree.png)
+
+The **IDE** caption says whether there is a repository at all — `code`, `code · git`,
+`code · worktree` — and the branch is inside the menu, with anything unpushed:
+
+![The IDE menu](screenshots/guide-ide-menu.png)
+
+### Removing one is guarded
+
+![Remove refuses to destroy unpushed work](screenshots/guide-remove-refusal.png)
+
+Two removals are refused before anything is deleted, because neither is recoverable and `rm -rf`
+warns about neither:
+
+- **the main checkout, while worktrees still live off it** — they would be left files with no
+  repository at all;
+- **anything holding commits that are on no remote**, or uncommitted changes.
+
+Tick the extra box (or pass `--force`) to go ahead anyway. Removing a worktree normally also prunes
+its registration in the main checkout, so a later clone to the same folder is not refused by git.
+
+---
+
+## Domains: what a project answers at
+
+![The domains dialog](screenshots/guide-domains.png)
+
+**DDEV → Domains this answers at…** lists the canonical address, the hierarchical one, and any extra
+ones, and offers `<project>-<workspace>` — the workspace in one flat hostname.
+
+It **adds**; it never renames. The canonical URL keeps working, nothing is rebuilt, and the DDEV
+project name goes on matching the folder. A new address reaches the router only when the project next
+starts, so the dialog offers to do that and says why.
+
+Two projects cannot share a hostname — the router gives it to whichever started last and the other
+quietly stops answering — so that is refused, naming the project that already has it.
+
+The clone form offers the same for the copy it is about to make, and the label follows the name as you
+type it:
+
+![The clone form's address option](screenshots/guide-clone-address.png)
+
+---
+
+## Screens: anything that takes time
+
+![The screens page](screenshots/guide-screens.png)
+
+Builds, installs, test suites and AI agents run in **screen sessions**, so they survive you closing
+the tab, logging out, or the dashboard restarting. This page lists them all and opens a real terminal
+on any of them — you can type into it.
+
+The useful part is the state. A session that has **stopped to ask you something** is flagged
+`✋ waiting on a choice` instead of looking busy for ever, which is the difference between a job that
+is running and a job that has been waiting for you for an hour.
+
+Every card has a **SCREENS** menu too: the sessions running in that project, **New screen here…**,
+**Claude Code here…**, and **Exit Claude Code** or **Resume Claude Code**.
+
+![The SCREENS menu on a card](screenshots/screens-menu.png)
+
+---
+
+## Settings
+
+![The settings page](screenshots/guide-settings.png)
+
+`core/config/settings.yml` and every `workspace.<name>.settings.yml`, edited from the browser. Two
+things about it are deliberate and worth knowing:
+
+- **A secret's value never leaves the server.** Anything whose key looks like a password, token or API
+  key renders as an empty field marked *set — leave blank to keep it*. The value is not in the page,
+  not in the response after saving, and not in `actions.log`.
+- **The file is rewritten line by line**, not parsed and re-dumped, so your comments and formatting
+  survive and a one-key change is a one-line diff.
+
+Every YAML list is edited as rows with an Add field, nested ones included
+(`auth.google.allowed_domains`, `auth.google.allowed_emails`):
+
+![The Google sign-in lists](screenshots/settings/auth-google-lists.png)
+
+The `workspaces:` list drags like the home page cards — that order is the card order. Adding one here
+creates the settings file, the folder and the DDEV hostname together. A workspace nothing uses can be
+deleted from its row, after three asks: the confirm dialog, its name typed, and `YES` typed.
+
+![Deleting an unused workspace: the last step](screenshots/settings/delete-4-type-yes.png)
+
+---
+
+## Keeping it up to date
+
+```bash
+bash core/workspace-app/scripts/update.sh --check   # what you have vs the latest release
+bash core/workspace-app/scripts/update.sh           # update the dashboard
+bash core/scripts/sync-tooling.sh --pull            # the cmd-*.sh commands and the shared core
+```
+
+The version you are on is in the toolbar. The updater touches **only** `core/workspace-app`, and it
+refuses the tooling job rather than half-doing it — so a release that adds or changes a `cmd-*.sh`
+needs `sync-tooling.sh --pull` as well, and the release notes say when.
+
+Some releases change the container image; the notes say so, and then
+`cd core/workspace-app && ddev restart` is needed too.
+
+> **If you are on 1.0.9 exactly**, run `bash core/scripts/docker-gid.sh` once. That release's updater
+> mirrored the release's `.ddev/` over yours without putting this machine's docker GID back, and the
+> symptom is delayed: nothing is wrong until the next `ddev restart`, when the dashboard shows **every
+> project as Stopped** while they all run perfectly well. The next release re-applies it for you.
+
+---
+
+## Where the rest is
+
+| | |
+| --- | --- |
+| changing the tooling | [DEVELOPER-GUIDE.md](DEVELOPER-GUIDE.md) |
+| installing, updating, the command chain | `README.md` at the top of this repository |
+| using it | [USER-GUIDE.md](USER-GUIDE.md) |
+| the dashboard's internals, DDEV wiring, the security note | `core/workspace-app/README.md` |
+| the hard rules and the operational traps | `docs/workspace-tips-and-rules.md` |
+| what changed, dated | `worklogs/` |
+
+Every picture in `screenshots/` is used by one of these guides or the top `README.md`, and all of them
+were taken on 22 October 2026 at 1920×1080, in light mode (the README's dark copies aside). A pull
+request carries its own pictures on its branch.