Add base instances for instance config inheritance

Instances can be marked as a base with instance.is_base and other
instances inherit config values from it through instance.base_id.
The controller copies base values into inheriting configs and keeps
track of inherited fields in the hidden instance.inherited_fields, so
hosts receive resolved configs and need no changes. Setting a field
stops inheriting it, `instance config inherit` undoes that.

Bases cannot be assigned to a host, are hidden from `instance list`
unless --bases is given, and cannot be deleted or unmarked while
other instances inherit from them. Chains of bases are allowed and
cycles are rejected.

Part of #200

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/configuration.md

@@ -521,6 +521,28 @@ This allows you to prevent certain instances from being started when using the b
 Defaults to false.
 
 
+### instance.is_base
+
+If enabled this instance is a base other instances can inherit config values from.
+Base instances cannot be assigned to a host and therefore never start.
+Hidden from `instance list` in clusterioctl unless `--bases` is passed.
+An instance cannot stop being a base while other instances inherit from it.
+
+Defaults to false.
+
+
+### instance.base_id
+
+ID of the base instance to inherit config values from.
+Inherited fields take their value from the base and follow it when it changes, setting a field on this instance stops inheriting it.
+When set on an existing instance only fields with the same value as the base become inherited.
+`instance.name`, `instance.is_base`, `instance.base_id` and hidden fields are never inherited.
+A base may itself inherit from another base, but not from itself through a chain of bases.
+The fields currently inherited are stored in the hidden `instance.inherited_fields` field.
+
+Defaults to null meaning no base.
+
+
 ### factorio.version
 
 Version of Factorio to use for this instance.

docs/managing-a-cluster.md

@@ -79,15 +79,16 @@ Marks the host as requiring a restart, the same way a plugin update does. Use it
 
 ### List Instances
 
-    ctl> instance list
+    ctl> instance list [--bases]
 
 List instances.
+Base instances are only listed if `--bases` is passed.
 
 ### Create instance
 
-    ctl> instance create <name> [--id <instance id>]
+    ctl> instance create <name> [--id <instance id>] [--from <instance id>] [--base <instance>] [--is-base]
 
-Create a new instance. `name` is the instance name. `--id` is the optional id.
+Create a new instance. `name` is the instance name. `--id` is the optional id. `--from` copies the config of an existing instance. `--base` makes the new instance inherit all config values from the given base instance. `--is-base` creates the instance as a base, see `instance.is_base` in the [configuration docs](configuration.md).
 
 ### Kill instance
 
@@ -120,7 +121,7 @@ Most notably Clusterio records wall clock time while the save time is recorded i
 
     ctl> instance config list <instance>
 
-List config values for an instance. `instance` is the instance whose config values to list.
+List config values for an instance. `instance` is the instance whose config values to list. Values inherited from a base instance are marked with `(inherited)`.
 
 #### Set config value
 
@@ -132,11 +133,17 @@ Set field in instance config. `instance` is instance to set. `field` is field to
 
 To be written.
 
+#### Inherit config value
+
+    ctl> instance config inherit <instance> <field>
+
+Make a field in the instance config take its value from the base instance again, undoing a previous `set`. `instance` is the instance to update, `field` is the field to inherit.
+
 #### Edit instance config
 
     ctl> instance config edit <instance> [editor]
 
-Edit instance config in a text editor. Once file is saved and editor has been exited, config values will be read back in. `instance` is the instance to edit, `editor` is the editor to use. If `editor` is not given, clusterioctl will read from the `EDITOR` or `VISUAL` enviroment variables.
+Edit instance config in a text editor. Once file is saved and editor has been exited, changed config values will be read back in. `instance` is the instance to edit, `editor` is the editor to use. If `editor` is not given, clusterioctl will read from the `EDITOR` or `VISUAL` enviroment variables.
 
 ### Assign instance to host