docs: less wordy

1 files changed, 13 insertions, 65 deletions

diff --git a/docs/workspaces.md b/docs/workspaces.md
index 2dbce4d..134b8b2 100644
--- a/docs/workspaces.md
+++ b/docs/workspaces.md
@@ -1,40 +1,12 @@
 # Workspaces
 
-A **project** is a directory on disk. A **workspace** is the tab it occupies in a
-session. Two words rather than one because the two have different lifetimes: the
-project outlives every session and is checked into git, the workspace lasts until
-you close the tab.
+slosh has the concept of **workspaces**. Essentially a workspace is a 
+pane layout that represents a project. slosh will scan your config's `project_roots`
+folder(s) for two kinds of sub folders: ones that have a `slosh.layout` file, and
+ones that have a `.git` but no `slosh.layout`. in the latter case our project picker
+can still pick it up and help you provision a new `slosh.layout`.
 
-[Finding a pane](panes.md#finding-a-pane) starts from the complaint this answers:
-tabs stop being navigation somewhere around six projects. The finder answers
-*where is that pane*; this answers the question before it: which of the things you
-work on is this tab about, and what does opening one mean. `C-a w`, a name, enter,
-and the tab arrives arranged, because the project itself said how.
-
-## What counts as a project
-
-A subdirectory of a configured root with one of two markers in it:
-
-| marker | what it is |
-|---|---|
-| `slosh.layout` | a *declared* project: it says what it needs open |
-| `.git` | an *inferred* one: you work here, but you have not said how |
-
-Anything else is not a project, and nothing is guessed from what is inside it.
-
-**`.git` counts because otherwise the list is empty on the day you configure the
-feature.** A picker that only knows declared projects shows nothing until you have
-written a layout, and there is nowhere to write one from: you would need the
-picker to get there. The inferred half is also the invitation: such a project reads
-`.git · no layout` in the picker, and `C-a W` is how it stops being one.
-
-**A directory that is a project is never descended into.** That is what keeps the
-scan out of `node_modules`, a vendored checkout or a submodule without a rule about
-any of their names: they are under a project, so the walk stops above them. A skip
-list is a list of the directories that were fashionable when it was written; this
-holds for the ones nobody has invented yet.
-
-## Where they live
+## Configuration options
 
 Two settings, both in your [config](config.md):
 
@@ -45,29 +17,7 @@ project_layout "~/.config/slosh/project.layout"
 
 `project_roots` takes more than one directory because people have more than one
 (work in one tree, everything else in another), and `depth` is how many levels below
-each root to look, 2 by default, 1 to 8. Two is `~/dev/thing` and
-`~/dev/org/thing`, which is where checkouts actually sit.
-
-**No roots configured and the feature is dormant.** Nothing is scanned, `C-a w`
-says which setting is missing rather than opening an empty picker, and `workspaces`
-answers `roots: false`, because "you have no projects" and "you never said where
-they are" are different facts, and a tool that cannot tell them apart reports the
-wrong one.
-
-`project_layout` is what a project with no file of its own opens as. **Relative
-paths in it bind to the project being opened, not to the directory the file lives
-in**, deliberately the opposite of the rule for a layout you name yourself, where
-a relative `cwd=` is relative to that file ([layouts](layouts.md#the-shape)). The
-whole point of one shared layout is that `cwd="."` means *this* project; bound to
-itself it would open every project in `~/.config/slosh`. Unset, a project opens
-as one pane running your shell in it.
-
-**Nothing sniffs `package.json` or `Cargo.toml` to guess what to run.** A table
-mapping manifests to commands is wrong for somebody the day it ships (the repo
-with two package managers, the one whose dev server is behind a make target) and
-stale for everybody a year later. `project_layout` is that table with your name on
-it, covering the projects you have rather than the ones a heuristic imagined, and a
-project that disagrees with it carries its own file.
+each root to look, 2 by default, 1 to 8.
 
 ## From the keyboard
 
@@ -145,11 +95,9 @@ otherwise: a shell's history and an editor's buffers are not in it.
 
 **Over the API, writing over a layout that is already there is refused without
 `force`; from the keyboard `C-a W` replaces it and the toast says `replaced`.**
-That asymmetry is not an oversight in either direction. A key cannot pass a flag,
-and the operator pressing it is looking at the tab being written; the file is
-committed text, so the diff is the confirmation and the replacement stays
-reviewable after the fact. A script has none of that (no witness, no glance at
-the screen) so it says so in the request.
+The asymmetry is deliberate: the operator pressing the key is looking at the
+tab being written, and the file is committed text, so the diff is the
+confirmation. A script has no witness, so it says so in the request.
 
 `save-workspace` also takes `path`, for a tab that is not a workspace yet: that is
 how a hand-arranged tab becomes a project's layout without opening it through the
@@ -218,9 +166,9 @@ Every one of them is in the bare dispatcher too, so `slosh -s work cmd
 workspaces` and `slosh -s work cmd open-workspace api` do the same from a shell
 without quoting JSON ([scripting](scripting.md#the-control-socket)).
 
-`open-workspace` is idempotent, which is the property that makes it safe to call
-from a script that does not know whether it ran already: asking twice focuses the
-tab rather than building a second one. `suspended:true` opens the layout with every
+`open-workspace` is idempotent: asking twice focuses the tab rather than
+building a second one, so a script that does not know whether it already ran is
+safe. `suspended:true` opens the layout with every
 pane suspended whatever the file said: the *open ten projects, run zero processes*
 case, which is a different question from the one the project answered about which
 of its own panes are expensive.