@webship.co/workspace 1.0.0-alpha1 → 1.0.0-beta2

package/core/config/theme.press.yml

@@ -0,0 +1,161 @@
+# Every token the "press" theme sets — core/config/theme.press.yml
+#
+# Webship Press. A theme is a palette: it declares custom properties and selects nothing, so every
+# value in it is configuration. They are all here, editable on the Settings screen, rather than
+# only by editing a stylesheet inside the app.
+#
+# Names go without the leading dashes. `tokens:` applies to both halves; `dark:` applies to the
+# dark half only, exactly like the html.dark block in a theme file. Anything here overrides the
+# theme CSS, which is what you get with no YAML at all.
+
+tokens:
+  brand-primary: "#0074e0"
+  brand-secondary: "#2b447c"
+  brand-accent: "#e4dcff"
+  brand-dark: "#000000"
+  brand-light: "#ebe8e5"
+  subtle-light: "#f5f3f2"
+  subtle-brand: "#deedff"
+  subtle-accent: "#f6f3ff"
+  text-default: "#000000"
+  text-subtle: "#4d4d4d"
+  text-inverse: "#ffffff"
+  text-light: "#ebe8e5"
+  text-brand: "var(--brand-primary)"
+  text-accent: "var(--brand-accent)"
+  font-primary: "Figtree, \"Helvetica Neue\", Arial, sans-serif"
+  font-secondary: "\"DM Serif Text\", Georgia, serif"
+  font-code: "\"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, monospace"
+  weight-regular: 400
+  weight-semibold: 600
+  leading-heading: 1.4
+  leading-display: 1.3
+  leading-body: 1.55
+  tracking-wide: 0.0625em
+  size-h1: 2.25rem
+  size-h2: 1.875rem
+  size-h3: 1.5rem
+  size-h4: 1.25rem
+  size-h5: 1.125rem
+  size-h6: 0.8125rem
+  size-body: 1rem
+  size-small: 0.875rem
+  type-h1: "var(--weight-regular) var(--size-h1)/1.15 var(--font-secondary)"
+  type-h2: "var(--weight-regular) var(--size-h2)/1.2 var(--font-secondary)"
+  type-h3: "var(--weight-semibold) var(--size-h3)/1.25 var(--font-primary)"
+  type-h4: "var(--weight-semibold) var(--size-h4)/1.3 var(--font-primary)"
+  type-h5: "var(--weight-semibold) var(--size-h5)/1.35 var(--font-primary)"
+  type-h6: "var(--weight-semibold) var(--size-h6)/1 var(--font-primary)"
+  type-body: "var(--weight-regular) var(--size-body)/var(--leading-body) var(--font-primary)"
+  type-body-sm: "var(--weight-regular) var(--size-small)/1.45 var(--font-primary)"
+  type-label: "var(--weight-semibold) var(--size-body)/1 var(--font-primary)"
+  type-caption: "var(--weight-regular) var(--size-small)/1.35 var(--font-primary)"
+  type-mono: "var(--weight-regular) var(--size-body)/1.5 var(--font-code)"
+  type-mono-sm: "var(--weight-regular) var(--size-small)/1.4 var(--font-code)"
+  tracking-h1: -0.02em
+  tracking-h2: -0.015em
+  tracking-h3: -0.01em
+  tracking-h4: -0.01em
+  tracking-h5: -0.005em
+  tracking-h6: 0.08em
+  surface: "var(--subtle-light)"
+  surface-card: "#ffffff"
+  surface-muted: "#f1eef9"
+  surface-input: "#ffffff"
+  text-subtle-2: "#333333"
+  line: "#e2ddd8"
+  line-strong: "#c9c2ba"
+  link: "#0063c0"
+  brand-pressed: "#0063c0"
+  brand-2-pressed: "#22355f"
+  focus-ring: "rgba(0, 116, 224, .35)"
+  ok: "#146c43"
+  ok-soft: "#d0e2d9"
+  pcard-tool-label: 0rem
+  ok-ink: "#14532d"
+  danger: "#e71139"
+  danger-soft: "#facfd7"
+  danger-ink: "#7d1a2e"
+  danger-armed: "#a4133c"
+  danger-text: "#c20f31"
+  warning: "#fdd26e"
+  warning-soft: "#fef1d3"
+  warning-ink: "#5c4300"
+  info: "#0dcaf0"
+  info-soft: "#cff4fc"
+  info-ink: "#055160"
+  success: "#146c43"
+  success-soft: "#d0e2d9"
+  success-ink: "#0f5132"
+  busy-soft: "var(--subtle-brand)"
+  busy-ink: "var(--brand-secondary)"
+  accent-soft: "var(--subtle-accent)"
+  accent-ink: "#4b3fa8"
+  chip-bg: "var(--brand-primary)"
+  chip-ink: "var(--text-inverse)"
+  shadow-card: "0 4px 16px rgba(35, 41, 70, .06)"
+  shadow-card-hover: "0 12px 28px rgba(43, 68, 124, .16)"
+  shadow-float: "0 1.5rem 3rem rgba(43, 68, 124, .28)"
+  shadow-toast: "0 14px 34px rgba(35, 41, 70, .26)"
+  toast-ring: "rgba(255, 255, 255, .9)"
+  code-bg: "#1f2437"
+  code-ink: "#e6e9f5"
+  terminal-ink: "#c9f7d4"
+  media-bg: "#000000"
+  paper: "#ffffff"
+  checker-a: "#dcdcdc"
+  checker-b: "#d8d8d8"
+  checker-bg: "#f4f4f4"
+  overlay: "rgba(0, 0, 0, .6)"
+  brand-1: "var(--brand-primary)"
+  brand-2: "var(--brand-secondary)"
+  brand-3: "var(--brand-accent)"
+  brand-grad: "linear-gradient(135deg, var(--brand-primary), var(--brand-secondary))"
+  ink: "var(--brand-secondary)"
+
+# The dark half. Only the tokens that differ at night are listed.
+dark:
+  surface: "#0f1626"
+  surface-card: "#172033"
+  surface-muted: "#1f2a42"
+  surface-input: "#0f1729"
+  text-default: "#e8edf6"
+  text-subtle-2: "#c2cbdd"
+  text-subtle: "#93a0b8"
+  line: "#27334d"
+  line-strong: "#3b4a6d"
+  link: "#57a8ff"
+  brand-pressed: "#2f8fe8"
+  brand-2-pressed: "#1b2b4d"
+  focus-ring: "rgba(87, 168, 255, .40)"
+  ok-soft: "#10261a"
+  ok-ink: "#a8e6b8"
+  danger-soft: "#2a1620"
+  danger-ink: "#ffd0da"
+  danger-armed: "#e0466b"
+  danger-text: "#ff8fa3"
+  warning-soft: "#2e2610"
+  warning-ink: "#fde4a3"
+  info-soft: "#0c2a33"
+  info-ink: "#9eeaf9"
+  success-soft: "#10291d"
+  success-ink: "#a3d9bd"
+  busy-soft: "#1a2440"
+  busy-ink: "#b9c9ff"
+  accent-soft: "#2c2550"
+  accent-ink: "#d9d2ff"
+  chip-bg: "#33406e"
+  chip-ink: "#e8edf6"
+  subtle-light: "#131b2c"
+  subtle-brand: "#10243d"
+  subtle-accent: "#221f3a"
+  shadow-card: "0 4px 16px rgba(0, 0, 0, .35)"
+  shadow-card-hover: "0 12px 28px rgba(0, 0, 0, .50)"
+  shadow-float: "0 1.5rem 3rem rgba(0, 0, 0, .55)"
+  shadow-toast: "0 14px 34px rgba(0, 0, 0, .50)"
+  toast-ring: "rgba(0, 0, 0, .5)"
+  checker-a: "#2a3550"
+  checker-b: "#26314a"
+  checker-bg: "#131b2c"
+  overlay: "rgba(0, 0, 0, .72)"
+  ink: "var(--text-default)"

package/core/config/theme.slate.yml

@@ -0,0 +1,160 @@
+# Every token the "slate" theme sets — core/config/theme.slate.yml
+#
+# Slate. A theme is a palette: it declares custom properties and selects nothing, so every
+# value in it is configuration. They are all here, editable on the Settings screen, rather than
+# only by editing a stylesheet inside the app.
+#
+# Names go without the leading dashes. `tokens:` applies to both halves; `dark:` applies to the
+# dark half only, exactly like the html.dark block in a theme file. Anything here overrides the
+# theme CSS, which is what you get with no YAML at all.
+
+tokens:
+  brand-primary: "var(--brand-secondary)"
+  brand-secondary: "#4f6d8c"
+  brand-accent: "#6b8fa8"
+  brand-grad: "linear-gradient(135deg, var(--brand-primary), var(--brand-secondary) 65%, var(--brand-accent))"
+  text-default: "#1f2933"
+  text-subtle-2: "#3e4c59"
+  text-subtle: "#7b8794"
+  surface: "#f4f6f8"
+  surface-card: "#fff"
+  surface-muted: "#e9edf1"
+  line: "#dde3e9"
+  line-strong: "#c3ccd5"
+  ok: "#2f855a"
+  ok-soft: "#f0f8f3"
+  pcard-tool-label: 0rem
+  ok-ink: "#1c4532"
+  danger: "#c53030"
+  danger-soft: "#fdf2f2"
+  danger-ink: "#742a2a"
+  danger-armed: "#9b2c2c"
+  danger-text: "#c53030"
+  warning: "#d69e2e"
+  warning-soft: "#fdf6e3"
+  warning-ink: "#744210"
+  info: "#3182ce"
+  info-soft: "#ebf4fb"
+  info-ink: "#2a4365"
+  success: "#146c43"
+  success-soft: "#d0e2d9"
+  success-ink: "#0f5132"
+  link: "#2f6a8d"
+  subtle-brand: "#eef3f7"
+  busy-soft: "#eaf1f5"
+  busy-ink: "var(--brand-secondary)"
+  subtle-light: "#f7fafc"
+  brand-1: "var(--brand-primary)"
+  brand-2: "var(--brand-secondary)"
+  font-code: "\"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, monospace"
+  font-primary: "Figtree, \"Helvetica Neue\", Arial, sans-serif"
+  font-secondary: "\"DM Serif Text\", Georgia, serif"
+  ink: "var(--brand-secondary)"
+  leading-body: 1.6
+  leading-display: 1.3
+  leading-heading: 1.4
+  size-body: 0.9375rem
+  size-h1: 2rem
+  size-h2: 1.625rem
+  size-h3: 1.5rem
+  size-h4: 1.25rem
+  size-h5: 1.125rem
+  size-h6: 1rem
+  subtle-accent: "#eef4f8"
+  weight-regular: 400
+  weight-semibold: 600
+  tracking-wide: 0.0625em
+  size-small: 0.875rem
+  type-h1: "var(--weight-regular) var(--size-h1)/1.15 var(--font-secondary)"
+  type-h2: "var(--weight-regular) var(--size-h2)/1.2 var(--font-secondary)"
+  type-h3: "var(--weight-semibold) var(--size-h3)/1.25 var(--font-primary)"
+  type-h4: "var(--weight-semibold) var(--size-h4)/1.3 var(--font-primary)"
+  type-h5: "var(--weight-semibold) var(--size-h5)/1.35 var(--font-primary)"
+  type-h6: "var(--weight-semibold) var(--size-h6)/1 var(--font-primary)"
+  type-body: "var(--weight-regular) var(--size-body)/var(--leading-body) var(--font-primary)"
+  type-body-sm: "var(--weight-regular) var(--size-small)/1.45 var(--font-primary)"
+  type-label: "var(--weight-semibold) var(--size-body)/1 var(--font-primary)"
+  type-caption: "var(--weight-regular) var(--size-small)/1.35 var(--font-primary)"
+  type-mono: "var(--weight-regular) var(--size-body)/1.5 var(--font-code)"
+  type-mono-sm: "var(--weight-regular) var(--size-small)/1.4 var(--font-code)"
+  tracking-h1: normal
+  tracking-h2: normal
+  tracking-h3: normal
+  tracking-h4: normal
+  tracking-h5: normal
+  tracking-h6: "var(--tracking-wide)"
+  brand-3: "var(--brand-accent)"
+  brand-dark: "#12171c"
+  brand-light: "#e4e9ee"
+  text-inverse: "#ffffff"
+  text-light: "#e4e9ee"
+  text-brand: "var(--brand-primary)"
+  text-accent: "var(--brand-accent)"
+  surface-input: "#ffffff"
+  brand-pressed: "#33698a"
+  brand-2-pressed: "#405a75"
+  focus-ring: "rgba(61, 126, 166, .35)"
+  accent-soft: "#eaf1f6"
+  accent-ink: "#2f5f7d"
+  chip-bg: "var(--brand-primary)"
+  chip-ink: "var(--text-inverse)"
+  shadow-card: "0 4px 16px rgba(31, 41, 51, .07)"
+  shadow-card-hover: "0 12px 28px rgba(31, 41, 51, .16)"
+  shadow-float: "0 1.5rem 3rem rgba(31, 41, 51, .26)"
+  shadow-toast: "0 14px 34px rgba(31, 41, 51, .24)"
+  toast-ring: "rgba(255, 255, 255, .9)"
+  code-bg: "#1b2229"
+  code-ink: "#dde5ec"
+  terminal-ink: "#a7d9bd"
+  media-bg: "#000000"
+  paper: "#ffffff"
+  checker-a: "#dcdcdc"
+  checker-b: "#d8d8d8"
+  checker-bg: "#f4f4f4"
+  overlay: "rgba(10, 14, 18, .6)"
+
+# The dark half. Only the tokens that differ at night are listed.
+dark:
+  text-default: "#e4e9ee"
+  text-subtle-2: "#bcc6d0"
+  text-subtle: "#8b97a5"
+  surface: "#12171c"
+  surface-card: "#1a2027"
+  surface-muted: "#161b21"
+  line: "#2a323b"
+  line-strong: "#3c4753"
+  ok-soft: "#14251c"
+  ok-ink: "#a7d9bd"
+  danger-soft: "#2a1618"
+  danger-ink: "#f0b4b4"
+  danger-armed: "#e05252"
+  danger-text: "#f28b8b"
+  warning-soft: "#2a2412"
+  warning-ink: "#f6d58e"
+  info-soft: "#12202c"
+  info-ink: "#9cc9ee"
+  success-soft: "#10291d"
+  success-ink: "#a3d9bd"
+  link: "#6aa9cc"
+  subtle-brand: "#1e262e"
+  busy-soft: "#10151a"
+  busy-ink: "#a7d9bd"
+  subtle-light: "#171d23"
+  surface-input: "#12171c"
+  brand-pressed: "#6aa9cc"
+  brand-2-pressed: "#3d566f"
+  focus-ring: "rgba(106, 169, 204, .40)"
+  accent-soft: "#1c2830"
+  accent-ink: "#a8cee2"
+  chip-bg: "#2f4250"
+  chip-ink: "#e4e9ee"
+  shadow-card: "0 4px 16px rgba(0, 0, 0, .38)"
+  shadow-card-hover: "0 12px 28px rgba(0, 0, 0, .52)"
+  shadow-float: "0 1.5rem 3rem rgba(0, 0, 0, .58)"
+  shadow-toast: "0 14px 34px rgba(0, 0, 0, .52)"
+  toast-ring: "rgba(0, 0, 0, .5)"
+  checker-a: "#2b343d"
+  checker-b: "#262e36"
+  checker-bg: "#171d23"
+  overlay: "rgba(0, 0, 0, .72)"
+  ink: "var(--text-default)"

package/core/config/theme.upsun.yml

@@ -0,0 +1,174 @@
+# UPSUN — core/config/theme.upsun.yml
+#
+# A style in the shape of the Upsun console. The values were read out of the console's own design
+# system — 584 custom properties on auth.upsun.com, which is the same system the console wears — so
+# the indigo, the ebony and the ice below are the ones it actually uses, not colours picked off a
+# screenshot.
+#
+# Its signatures: the #6046ff indigo primary, a very dark ebony-to-night ink, an #f2f3f4 page under
+# white cards, and Open Sans throughout. Open Sans is not vendored here, so a machine without it
+# falls back through the stack.
+
+# What was measured and what was not, because the two are different here.
+#
+# The COLOURS are the console's own, read from the 584 custom properties its design system declares.
+# The FAMILY is its own too: Open Sans, throughout, for headings as well as body.
+#
+# The heading SCALE is not. The page those values came from leaves bare headings at the browser's
+# defaults — 32 / 24 / 18.72px and so on — which is the user agent stylesheet, not a design system,
+# and the console itself is behind a login. So the heading ramp here is this workspace's, not
+# Upsun's, and that is stated rather than implied by a number that looks measured.
+
+name: UPSUN
+
+tokens:
+  brand-primary: "#6046ff"
+  brand-secondary: "#302f45"
+  brand-accent: "#efe7ff"
+  brand-dark: "#01001a"
+  brand-light: "#f5f7fa"
+  subtle-light: "#f5f7fa"
+  subtle-brand: "#efedff"
+  subtle-accent: "#efe7ff"
+  text-default: "#1a192b"
+  text-subtle: "#5f5e70"
+  text-inverse: "#ffffff"
+  text-light: "#f5f7fa"
+  text-brand: "var(--brand-primary)"
+  text-accent: "var(--brand-accent)"
+  font-primary: "\"Open Sans\", Helvetica, Arial, sans-serif"
+  font-secondary: "\"Open Sans\", Helvetica, Arial, sans-serif"
+  font-code: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+  weight-regular: 400
+  weight-semibold: 600
+  leading-heading: 1.4
+  leading-display: 1.3
+  leading-body: 1.5
+  tracking-wide: 0.0625em
+  size-h1: 2rem
+  size-h2: 1.625rem
+  size-h3: 1.5rem
+  size-h4: 1.25rem
+  size-h5: 1.125rem
+  size-h6: 1rem
+  size-body: 0.9375rem
+  size-small: 0.875rem
+  type-h1: "var(--weight-semibold) var(--size-h1)/1.2 var(--font-primary)"
+  type-h2: "var(--weight-semibold) var(--size-h2)/1.25 var(--font-primary)"
+  type-h3: "var(--weight-semibold) var(--size-h3)/1.25 var(--font-primary)"
+  type-h4: "var(--weight-semibold) var(--size-h4)/1.3 var(--font-primary)"
+  type-h5: "var(--weight-semibold) var(--size-h5)/1.35 var(--font-primary)"
+  type-h6: "var(--weight-semibold) var(--size-h6)/1 var(--font-primary)"
+  type-body: "var(--weight-regular) var(--size-body)/var(--leading-body) var(--font-primary)"
+  type-body-sm: "var(--weight-regular) var(--size-small)/1.45 var(--font-primary)"
+  type-label: "var(--weight-semibold) var(--size-body)/1 var(--font-primary)"
+  type-caption: "var(--weight-regular) var(--size-small)/1.35 var(--font-primary)"
+  type-mono: "var(--weight-regular) var(--size-body)/1.5 var(--font-code)"
+  type-mono-sm: "var(--weight-regular) var(--size-small)/1.4 var(--font-code)"
+  tracking-h1: normal
+  tracking-h2: normal
+  tracking-h3: normal
+  tracking-h4: normal
+  tracking-h5: normal
+  tracking-h6: "var(--tracking-wide)"
+  surface: "#f2f3f4"
+  surface-card: "#ffffff"
+  surface-muted: "#f9f9f9"
+  surface-input: "#ffffff"
+  text-subtle-2: "#302f45"
+  line: "#e7e7e7"
+  line-strong: "#c9d0e4"
+  link: "#6046ff"
+  brand-pressed: "#3a2a99"
+  brand-2-pressed: "#1a192b"
+  focus-ring: "#86b5ff4c"
+  ok: "#23b7b7"
+  ok-soft: "#d6f6ef"
+  pcard-tool-label: 0rem
+  ok-ink: "#188181"
+  danger: "#fb3728"
+  danger-soft: "#fce1e1"
+  danger-ink: "#6d144f"
+  danger-armed: "#ff5d25"
+  danger-text: "#fb3728"
+  warning: "#eda900"
+  warning-soft: "#fcf4db"
+  warning-ink: "#9a6f1e"
+  info: "#86b5ff"
+  info-soft: "#efedff"
+  info-ink: "#302f45"
+  success: "#146c43"
+  success-soft: "#d0e2d9"
+  success-ink: "#0f5132"
+  busy-soft: "var(--subtle-brand)"
+  busy-ink: "var(--brand-secondary)"
+  accent-soft: "#efe7ff"
+  accent-ink: "#9d67ff"
+  chip-bg: "#6046ff"
+  chip-ink: "#ffffff"
+  shadow-card: "0 4px 16px rgba(35, 41, 70, .06)"
+  shadow-card-hover: "0 12px 28px rgba(43, 68, 124, .16)"
+  shadow-float: "0 1.5rem 3rem rgba(43, 68, 124, .28)"
+  shadow-toast: "0 14px 34px rgba(35, 41, 70, .26)"
+  toast-ring: "rgba(255, 255, 255, .9)"
+  code-bg: "#1a192b"
+  code-ink: "#f5f7fa"
+  terminal-ink: "#c9f7d4"
+  media-bg: "#000000"
+  paper: "#ffffff"
+  checker-a: "#dcdcdc"
+  checker-b: "#d8d8d8"
+  checker-bg: "#f4f4f4"
+  overlay: "#1a1a2be5"
+  brand-1: "var(--brand-primary)"
+  brand-2: "var(--brand-secondary)"
+  brand-3: "var(--brand-accent)"
+  brand-grad: "linear-gradient(135deg, var(--brand-primary), var(--brand-secondary))"
+  ink: "var(--brand-secondary)"
+
+# The dark half.
+dark:
+  surface: "#1a192b"
+  surface-card: "#232235"
+  surface-muted: "#302f45"
+  surface-input: "#1a1a2b"
+  text-default: "#f5f7fa"
+  text-subtle-2: "#c9d0e4"
+  text-subtle: "#98a0ab"
+  line: "#4a495e"
+  line-strong: "#5f5e70"
+  link: "#86b5ff"
+  brand-pressed: "#9d67ff"
+  brand-2-pressed: "#302f45"
+  focus-ring: "#86b5ff4c"
+  ok-soft: "#188181"
+  ok-ink: "#d6f6ef"
+  danger-soft: "#6d144f"
+  danger-ink: "#fce1e1"
+  danger-armed: "#e0466b"
+  danger-text: "#ff8fa3"
+  warning-soft: "#9a6f1e"
+  warning-ink: "#fcf4db"
+  info-soft: "#302f45"
+  info-ink: "#86b5ff"
+  success-soft: "#10291d"
+  success-ink: "#a3d9bd"
+  busy-soft: "#1a2440"
+  busy-ink: "#b9c9ff"
+  accent-soft: "#4a495e"
+  accent-ink: "#c9d0e4"
+  chip-bg: "#6046ff"
+  chip-ink: "#ffffff"
+  subtle-light: "#232235"
+  subtle-brand: "#302f45"
+  subtle-accent: "#4a495e"
+  shadow-card: "0 4px 16px rgba(0, 0, 0, .35)"
+  shadow-card-hover: "0 12px 28px rgba(0, 0, 0, .50)"
+  shadow-float: "0 1.5rem 3rem rgba(0, 0, 0, .55)"
+  shadow-toast: "0 14px 34px rgba(0, 0, 0, .50)"
+  toast-ring: "rgba(0, 0, 0, .5)"
+  checker-a: "#2a3550"
+  checker-b: "#26314a"
+  checker-bg: "#131b2c"
+  overlay: "#01001ae5"
+  ink: "var(--text-default)"

package/core/docs/architecture.svg

@@ -0,0 +1,65 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 420" width="960" height="420" font-family="Inter, 'Segoe UI', Helvetica, Arial, sans-serif">
+  <defs>
+    <style>
+      .t { fill: #1b2a4a; font-size: 14px; }
+      .h { fill: #1b2a4a; font-size: 17px; font-weight: 600; }
+      .m { fill: #5b6b85; font-size: 12px; }
+      .box { fill: #ffffff; stroke: #c9d3e3; stroke-width: 1.5; rx: 10; }
+      .core { fill: #eef3ff; stroke: #2f6fed; stroke-width: 2; rx: 12; }
+      .fam { fill: #f7f9fc; stroke: #c9d3e3; stroke-width: 1.5; rx: 10; }
+      .pill { fill: #ffffff; stroke: #2f6fed; stroke-width: 1.2; rx: 14; }
+      .pt { fill: #2f6fed; font-size: 12px; font-weight: 600; }
+      .line { stroke: #2f6fed; stroke-width: 1.5; fill: none; marker-end: url(#arrow); }
+    </style>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#2f6fed"/></marker>
+  </defs>
+  <rect width="960" height="420" fill="#ffffff"/>
+
+  <!-- the core -->
+  <rect x="30" y="40" width="300" height="340" class="core"/>
+  <text x="50" y="72" class="h">@webship.co/workspace</text>
+  <text x="50" y="92" class="m">the core — ships empty</text>
+  <rect x="50" y="112" width="260" height="52" class="box"/>
+  <text x="64" y="134" class="t">Dashboard</text>
+  <text x="64" y="152" class="m">node:http + HTMX, in a DDEV container</text>
+  <rect x="50" y="176" width="260" height="52" class="box"/>
+  <text x="64" y="198" class="t">Plugin system</text>
+  <text x="64" y="216" class="m">require · activate · install · configure</text>
+  <rect x="50" y="240" width="260" height="52" class="box"/>
+  <text x="64" y="262" class="t">Settings, workspaces list, builders, jobs</text>
+  <text x="64" y="280" class="m">core/config · core/scripts · screen sessions</text>
+  <rect x="50" y="304" width="260" height="52" class="box"/>
+  <text x="64" y="326" class="t">webship-workspace</text>
+  <text x="64" y="344" class="m">init · plugin · catalog · update</text>
+
+  <!-- arrows -->
+  <path d="M330,120 C380,120 380,86 420,86" class="line"/>
+  <path d="M330,200 C380,200 380,186 420,186" class="line"/>
+  <path d="M330,260 C380,260 380,286 420,286" class="line"/>
+  <path d="M330,330 C380,330 380,366 420,366" class="line"/>
+
+  <!-- families -->
+  <rect x="420" y="56" width="510" height="60" class="fam"/>
+  <text x="436" y="80" class="t">Workspace folders</text>
+  <text x="436" y="98" class="m">dev · test · drupal-modules · drupal-themes · docs · images · ai-agents · graph · rag …</text>
+
+  <rect x="420" y="156" width="510" height="60" class="fam"/>
+  <text x="436" y="180" class="t">Hosting providers</text>
+  <text x="436" y="198" class="m">upsun · acquia · digitalocean · cpanel · aws · azure · godaddy — one base, one button per provider</text>
+
+  <rect x="420" y="256" width="250" height="60" class="fam"/>
+  <text x="436" y="280" class="t">Git forges</text>
+  <text x="436" y="298" class="m">github · gitlab · bitbucket</text>
+
+  <rect x="680" y="256" width="250" height="60" class="fam"/>
+  <text x="696" y="280" class="t">Container runtimes</text>
+  <text x="696" y="298" class="m">docker · lando · docksal · podman · k8s</text>
+
+  <rect x="420" y="336" width="510" height="60" class="fam"/>
+  <text x="436" y="360" class="t">Features</text>
+  <text x="436" y="378" class="m">git · ide · jira · google-drive · testing · webship-js · drupal · wordpress · odoo · microsoft · apple</text>
+
+  <!-- the pill -->
+  <rect x="600" y="8" width="330" height="28" class="pill"/>
+  <text x="614" y="27" class="pt">each one an npm package: @webship.co/workspace-&lt;name&gt;</text>
+</svg>

package/core/docs/getting-started.md

@@ -0,0 +1,51 @@
+# Getting started
+
+The Webship Workspace is a folder (`~/workspace` by default) with a web dashboard in it. The dashboard runs in a DDEV container and drives everything else: it builds, starts, stops, backs up and restores real projects through the `cmd-*.sh` scripts in each workspace folder, with live terminal output, and it embeds an AI assistant that knows the page you are on.
+
+## What you need
+
+- Node.js 20 or newer (24 is what the dashboard runs on).
+- Docker, and [DDEV](https://ddev.readthedocs.io/en/stable/users/install/). DDEV is the only runtime the core needs; other container runtimes come as plugins.
+- A terminal. Windows works through WSL2.
+
+## The first hour
+
+```bash
+npm install -g @webship.co/workspace
+webship-workspace init ~/workspace
+```
+
+`init` copies the core into the folder, writes `core/config/settings.yml` from the lean template (no workspace folders, no plugins), installs the dashboard's dependencies and starts it. Open https://workspace.ddev.site.
+
+The dashboard is empty on purpose. Add a workspace folder:
+
+```bash
+webship-workspace plugin require dev
+webship-workspace plugin activate dev
+webship-workspace plugin install dev
+```
+
+Now `dev/` exists with its builders (`cmd-drupal11-recommended-project.sh`, `cmd-webship11-0-x-project.sh`, …) and its settings file, and the dashboard shows the Dev workspace with a Build button. Build a site from the dashboard, or from the folder:
+
+```bash
+cd ~/workspace/dev
+bash cmd-drupal11-recommended-project.sh mysite
+```
+
+Every build goes through DDEV; the site answers at `https://mysite.ddev.site`.
+
+## Then
+
+- **Settings → Plugins** shows the catalogue. Add the GIT menu (`git`), the Web IDE (`ide`), a hosting provider (`upsun`, `acquia`, …), a git forge (`github`, `gitlab`, `bitbucket`), or more workspace folders (`test`, `drupal-modules`, `docs`, `ai-agents`, …).
+- Each plugin with settings gets its own file, `core/config/plugin.<name>.settings.yml`, edited from Settings. Secrets live there, never in `settings.yml`.
+- `webship-workspace update ~/workspace` refreshes the core from a newer package without touching your settings files.
+
+## Where things are
+
+| Path | What it is |
+| --- | --- |
+| `core/workspace-app` | The dashboard (Node.js + HTMX), a DDEV project of its own |
+| `core/scripts` | The bash tooling every `cmd-*.sh` sources: bootstrap, builders, `plugins.sh` |
+| `core/config` | `settings.yml`, one `workspace.<key>.settings.yml` per folder, one `plugin.<name>.settings.yml` per plugin |
+| `<folder>/` | A workspace folder: its `cmd-*.sh` commands and the projects or items it holds |
+| `backups/` | What Back up wrote, per workspace and project |

package/core/docs/plugins.md

@@ -0,0 +1,27 @@
+# Plugins
+
+Everything optional is a plugin: an npm package `@webship.co/workspace-<name>`, from the repository `github.com/webship/workspace-<name>` on branch `1.0.x`. The core requires none of them. A plugin requires nothing from the dashboard's files; it is handed an `api` and works through it, so it can be installed from npm and removed without a trace.
+
+## The four steps
+
+| Step | Command | What happens |
+| --- | --- | --- |
+| require | `webship-workspace plugin require <name>` | `npm install @webship.co/workspace-<name>` into `core/workspace-app/package.json` |
+| activate | `webship-workspace plugin activate <name>` | `plugins.<name>.enabled: true` in `settings.yml`; a workspace plugin also joins the `workspaces:` list |
+| install | `webship-workspace plugin install <name>` | places what the manifest names: bash functions, commands, compose files, themes, a workspace folder, a settings template; recorded in `core/config/plugins.installed.yml` |
+| configure | `webship-workspace plugin configure <name>` | its own `core/config/plugin.<name>.settings.yml` |
+
+The same four are buttons on **Settings → Plugins**, below the catalogue. `deactivate` turns one off and keeps its files; `uninstall` removes what install placed. `bash core/scripts/plugins.sh --list` says the step each plugin is at.
+
+## Families
+
+Plugins that do the same job for different services share a base package, so a provider is thin and the surface is one:
+
+- **Hosting** — `@webship.co/workspace-hosting`: one button per provider, with environments and live URLs, get the database and files, deploy, logs, activities and the console. Providers: upsun, acquia, digitalocean, cpanel, aws, azure, godaddy.
+- **Forges** — `@webship.co/workspace-forge`: the repository, open issues and pull or merge requests, a request from the current branch, the clone option, and the credential the dashboard uses for the host. Providers: github, gitlab, bitbucket.
+- **Container runtimes** — `@webship.co/workspace-container`: a menu for projects on Docker Compose, Lando, Docksal, Podman or Kubernetes.
+- **Workspace folders** — the folder itself as a plugin: its settings file, its commands, its docs. Activating one lists it on the dashboard.
+
+## Writing one
+
+Read [PLUGINS.md](../workspace-app/PLUGINS.md): the manifest (`workspacePlugin` in `package.json`), `register(api)`, the hooks (row menus, pages, fragments, actions, chips, folder setup, forges, open-with, workspace views) and `api.lib`. Types come from `@webship.co/workspace-plugin-api`. The reference plugins are `workspace-upsun` (a hosting provider), `workspace-github` (a forge), `workspace-lando` (a runtime) and `workspace-drupal-modules` (a workspace folder); each has tests, a `features/*.feature` the installer places under the dashboard's browser suite, and a CI workflow.

package/core/docs/releases.md

@@ -0,0 +1,23 @@
+# Releases
+
+Every package is versioned together: `@webship.co/workspace` (the core) and every `@webship.co/workspace-<name>`. Versions so far: 1.0.0-alpha1 (the first publish), 1.0.0-beta1.
+
+## How a change lands
+
+1. An issue on the repository it belongs to (`github.com/webship/workspace` for the core, `workspace-<name>` for a plugin), with the Checkpoints list.
+2. A branch and a pull request against `1.0.x`, referencing the issue.
+3. The unit tests and the browser suite pass; a human reviews; the pull request is merged.
+
+## Publishing
+
+Bases first (`workspace-plugin-api`, `workspace-hosting`, `workspace-forge`, `workspace-container`), then the providers and the rest, then the core — one package at a time with a pause between them, within npm's publishing limits. A dependency on a sibling is a version range (`^1.0.0-beta1`), never a git URL.
+
+## Upgrading a workspace
+
+```bash
+npm install -g @webship.co/workspace@latest
+webship-workspace update ~/workspace
+cd ~/workspace/core/workspace-app && npm update
+```
+
+`update` refreshes the core and keeps every settings file; `npm update` moves the installed plugins to their newest versions within the ranges in `package.json`.