docs: server tags and workflow tag targeting

docsite/docs/vantage/servers.md

@@ -26,6 +26,52 @@ The offline sweep runs every two minutes, so a machine that has just gone away
 takes a little while to be marked as such. That delay is intentional a single
 missed poll is not an outage.
 
+## Tags
+
+A tag is a `key:value` label you put on a server. Tags are how you say what a
+machine **is** `env:prod`, `role:web`, `team:core-infra` so that you can find
+it later, and so that a [workflow](./workflows.md) can target it without you
+naming it by hand.
+
+There is no tag library to manage first. A tag exists because a server carries
+it, and it stops existing when the last server carrying it drops it.
+
+### The rules
+
+| Rule       | Value                                             |
+| ---------- | ------------------------------------------------- |
+| Characters | lowercase letters, digits, `-` and `_`, on both halves |
+| Key length | up to 32 characters                               |
+| Value length | up to 64 characters                             |
+| Per server | up to 20 tags                                     |
+
+Neither half may be empty, and keys beginning `sys:` are reserved for tags
+Vantage may derive from inventory later, so a tag you write today can never
+collide with one invented for you tomorrow.
+
+Anything outside those rules is refused with a message naming the rule, rather
+than quietly saved in a shape you did not intend. Uppercase is not folded to
+lowercase for you `Env` is a mistake, not a synonym for `env`.
+
+### Editing a server's tags
+
+On the server detail page, **Edit** beside the tag chips. Saving replaces the
+whole set: what you see in the editor is exactly what the server will have.
+There is no per-tag merge, so if two people edit the same server at once, the
+last save wins outright rather than producing a blend of the two.
+
+### Filtering the fleet
+
+The **Servers** list has a picker per tag key in use. Choosing values from more
+than one key narrows the list a server must match **all** of them, not any.
+Untagged servers appear only when no filter is set.
+
+:::tip A filtered fleet view is a link
+The filter lives in the URL (`/servers?tag=env:prod&tag=role:web`). Copy the
+address bar and you have sent someone the same view, not a description of how to
+reproduce it.
+:::
+
 ## The server detail page
 
 ### Keys

docsite/docs/vantage/workflows.md

@@ -76,7 +76,8 @@ the API is the boundary; the UI is the courtesy.
 2. Add steps in order from the library.
 3. Set inputs per step.
 4. Set failure behaviour per step.
-5. Choose target servers.
+5. Choose targets: named servers, a tag selector, or both. See
+   [Targeting](#targeting).
 
 ### Failure behaviour
 
@@ -92,6 +93,48 @@ A workflow can override a step's script or its secret references without
 touching the library entry. This is how you adapt a default step, and it is
 scoped to that workflow.
 
+## Targeting
+
+A workflow names servers two ways, and it can use both at once:
+
+- **Target servers** an explicit list you pick from the fleet.
+- **Target tags** a `key:value` selector matched against
+  [server tags](./servers.md#tags). More than one key ANDs: a server must carry
+  every pair to match.
+
+A run goes to the **union** of the two, with duplicates removed. A server that is
+both named explicitly and matched by the selector runs once, not twice. This is
+what lets a workflow say "every production web server, plus this one box I am
+watching" without maintaining a list.
+
+The designer shows the resolved count as you edit, so you can see how many
+machines a change to the selector just added or removed before you save.
+
+:::warning An empty selector matches nothing
+Clearing the tag selector does not mean "all servers". A workflow with no named
+servers and no tags matches nothing and is refused at run time rather than
+reported as a success over zero machines.
+
+The alternative reading, where an empty field means the whole fleet, turns a
+cleared box into a fleet-wide run. That is not a mistake anyone should be able to
+make by deleting text.
+:::
+
+Tags are read **at run time**, not when you save. Tag a new machine `env:prod`
+and the next run of an `env:prod` workflow includes it, with nothing to update on
+the workflow itself. The same is true in reverse: removing a tag removes the
+machine from every workflow that selected on it.
+
+### Offline servers are still targeted
+
+A server matched by tag is dispatched to even if its agent is offline, and that
+step fails visibly on that machine. Vantage does not quietly shrink your target
+list to the machines that happened to be reachable a patch run that skipped
+three servers and reported success is worse than one that failed on three and
+said so.
+
+Re-run the workflow once they are back, or fix the agent first.
+
 ## Running
 
 **Run** snapshots the resolved steps into the run record and dispatches each step