@takodotid/circuit 0.26.0 → 0.26.1

package/README.md

@@ -11,13 +11,13 @@ Documentation: [circuit.tako.id](https://circuit.tako.id)
 
 - **One file per device.** VLANs, ports, addresses, routing, firewall, users and services, written in TypeScript. Your editor checks every name you refer to as you type.
 - **The same words for every vendor.** MikroTik RouterOS 7, Huawei VRP, Raisecom ROS, Juniper Junos and Fortinet FortiOS each get their own commands. What a device cannot do is an error before anything is sent.
-- **The file is the whole truth.** A port, user or service the file does not mention is removed or turned off, so nothing set by hand lingers.
+- **The file is the whole truth.** A port, user or service the file does not mention is removed or turned off, so nothing set by hand stays behind.
 - **See every change first.** `diff` shows it offline, `apply` plans it against the live device, and nothing is sent without `--confirm`. On RouterOS, Junos and FortiOS, a change undoes itself if Circuit cannot log in again afterwards.
 - **History in git.** Each device's last snapshot is kept in `.circuit/state/`, so the repository's history is the network's history.
 - **Rules of your own.** Checks run on every change, and presets give ready-made filters, BGP policies and checks.
 - **Secrets stay out of the repository.** They come from `.env` or 1Password, and never appear in a plan or a snapshot.
-- **See the network.** Circuit Studio, started with `circuit studio`, draws the cables, VLANs, addresses, BGP sessions, OSPF neighbors and tunnels in your browser, and marks what is broken or differs from the device. Its tables list everything each device holds, for anyone who does not read TypeScript, and it can run on a server for the whole team. `circuit graph` prints the drawing as Mermaid, DOT or JSON.
-- **Keeps the rest in step.** Prefix lists fetched from a registry, your PeeringDB record, devices in LibreNMS, targets for Prometheus, WireGuard client configs, and your BGP communities for a looking glass.
+- **See the network.** Circuit Studio, started with `circuit studio`, draws the cables, VLANs, addresses, BGP sessions, OSPF neighbors and tunnels in your browser, and marks what is broken or differs from the device. Its tables list everything each device has, for anyone who does not read TypeScript, and it can run on a server for the whole team. `circuit graph` prints the drawing as Mermaid, DOT or JSON.
+- **Keeps the rest up to date.** Prefix lists fetched from a registry, your PeeringDB record, devices in LibreNMS, targets for Prometheus, WireGuard client configs, and your BGP communities for a looking glass.
 - **Safe with AI agents.** Every project gets an `AGENTS.md` that tells an agent what it may run, and the last step stays yours.
 
 <picture>
@@ -27,7 +27,7 @@ Documentation: [circuit.tako.id](https://circuit.tako.id)
 
 ## Circuit Academy
 
-New to networking? [Circuit Academy](https://circuit.tako.id/academy/) teaches it from the very start, in lessons you try in the browser rather than only read: packets, addresses, switches and routers first, then VLANs, DHCP, NAT and firewalls written down in Circuit, up to BGP and an edge router of your own. A certification is coming.
+New to networking? [Circuit Academy](https://circuit.tako.id/academy/) teaches it from the very start, in lessons you try in the browser rather than only read: packets, addresses, switches and routers first, then VLANs, DHCP, NAT and firewalls written down in Circuit, BGP and an edge router of your own, and on to running a provider network. A certification is coming.
 
 <picture>
     <source media="(prefers-color-scheme: dark)" srcset="docs/public/screenshots/academy-dark.png">

package/dist/types/schema/common.d.ts

@@ -7,7 +7,7 @@ export type Secret = {
     /** Name of the value in the environment or in `.env`. */
     readonly secret: string;
 } | {
-    /** Path of a file holding the value, relative to the config file. */
+    /** Path of the file with the value, relative to the config file. */
     readonly secret_file: string;
 };
 /** An address without a length, IPv4 or IPv6, for example `10.0.0.1`. */

package/dist/types/schema/device.d.ts

@@ -26,7 +26,7 @@ export type Vrf = {
 export type Device<Pl extends string = string, M extends string = string, N extends string = string, V extends string = string, I extends string = string, P extends string = string, S extends string = string, G extends string = string, A extends string = string, AS extends string = string, U extends string = string, F extends string = string, C extends string = string> = {
     /** Hostname. */
     name: string;
-    /** Operating system, which decides the adapter that renders and applies the device. */
+    /** Operating system. It decides which adapter renders and applies the device. */
     platform: Pl;
     /** Hardware model. Decides which port names exist. */
     model: M;

package/dist/types/schema/firewall.d.ts

@@ -12,7 +12,7 @@ export type PortRange = {
 export type Ports = number | PortRange | readonly (number | PortRange)[];
 /** A TCP header flag. */
 export type TcpFlag = "fin" | "syn" | "rst" | "psh" | "ack" | "urg";
-/** Conditions on a packet. All must hold. A rule with addresses of one family applies to that family only. */
+/** Conditions on a packet. All must be true. A rule with addresses of one family applies to that family only. */
 export type FilterMatch<I extends string, AS extends string> = {
     /** Only packets of this family. */
     family?: Family;
@@ -50,7 +50,7 @@ export type FilterRule<I extends string, AS extends string> = {
     match?: FilterMatch<I, AS>;
     /** What happens to a matching packet. `reject` answers the sender, `drop` does not. */
     action: "accept" | "drop" | "reject";
-    /** Hand the rest of an accepted flow to the fast path, past the remaining rules. */
+    /** Send the rest of an accepted flow through the fast path, skipping the remaining rules. */
     offload?: true;
 };
 /** Rules evaluated in order, first match wins, then `default`. */
@@ -117,7 +117,7 @@ export type AclRule<V extends string> = {
         src_port?: Ports;
         /** Destination port, or any of several. */
         dst_port?: Ports;
-        /** Carried in this VLAN. */
+        /** In this VLAN. */
         vlan?: V;
     };
     /** What happens to a matching packet. */

package/dist/types/schema/interfaces.d.ts

@@ -1,7 +1,7 @@
 import type { Address, IP, Prefix, Secret } from "./common";
-/** A VLAN. The key it is declared under is its name. */
+/** A VLAN. Its key in `vlans` is its name. */
 export type Vlan = {
-    /** The number carried on the wire, 1 to 4094. */
+    /** The VLAN's number on the wire, 1 to 4094. */
     id: number;
     /** What the VLAN is for. */
     description?: string;
@@ -25,7 +25,7 @@ export type Vrrp = {
     /** Seconds between advertisements. 1 when absent. */
     interval?: number;
 };
-/** Layer 3 settings shared by every interface that can hold an address. */
+/** Layer 3 settings shared by every interface that can have an address. */
 export type Routed<F extends string> = {
     /** Addresses with their length. Use `{ address, peer }` for a point-to-point address whose far end is outside its own prefix. */
     addresses?: readonly (Address | {
@@ -36,7 +36,7 @@ export type Routed<F extends string> = {
     ipv6_ra?: boolean;
     /** Overrides the device's `hardware_offload` for traffic routed through this interface. Software forwarding is what makes the firewall apply. */
     hardware_offload?: boolean;
-    /** Virtual router addresses held on this interface. */
+    /** Virtual router addresses on this interface. */
     vrrp?: readonly Vrrp[];
     /** The VRF this interface routes in. The default table when absent. */
     vrf?: F;
@@ -63,11 +63,11 @@ export type PortStp = {
 };
 /** Layer 2 membership. A port or LAG with none of these is routed. */
 export type Switched<V extends string> = {
-    /** Untagged member of one VLAN. */
+    /** The one VLAN this port or LAG is in, untagged. */
     access_vlan?: V;
-    /** Tagged member of these VLANs. */
+    /** The VLANs this port or LAG carries, tagged. */
     trunk_vlans?: readonly V[];
-    /** Untagged frames on a trunk belong to this VLAN. Only with `trunk_vlans`. */
+    /** Untagged frames on a trunk are in this VLAN. Only with `trunk_vlans`. */
     native_vlan?: V;
     /** Overrides the device's `stp` for this port. `false` stops it sending or acting on BPDUs. */
     stp?: boolean | PortStp;
@@ -97,7 +97,7 @@ export type Port<V extends string, A extends string, L extends string, F extends
     lldp?: boolean;
     /** Hardware ACL applied to traffic arriving on this port. */
     acl?: A;
-    /** Member of this LAG. The LAG holds every other setting. */
+    /** The LAG this port is in. Every other setting goes on the LAG. */
     lag?: L;
     /** Another of our devices at the other end of the cable. */
     link?: Link;
@@ -112,19 +112,19 @@ type Base<F extends string> = Routed<F> & {
 /** A layer 3 interface on a VLAN. */
 export type VlanInterface<V extends string, F extends string> = Base<F> & {
     type: "vlan";
-    /** The VLAN it sits on. */
+    /** The VLAN it is on. */
     vlan: V;
 };
-/** An interface that is always up and belongs to no link, for addresses that must not depend on one. */
+/** An interface that is always up and is on no link, for addresses that must not depend on one. */
 export type Loopback<F extends string> = Base<F> & {
     type: "loopback";
 };
-/** A link aggregation. Member ports name it with `lag`. */
+/** A link aggregation. Each member port points to it with `lag`. */
 export type Lag<V extends string, F extends string> = Base<F> & Switched<V> & {
     type: "lag";
-    /** LACP negotiates membership with the far end; static bundles without asking. LACP when absent. */
+    /** LACP negotiates membership with the far end; `static` joins the ports without asking. LACP when absent. */
     mode?: "lacp" | "static";
-    /** Number on platforms that name a LAG by number. Its position among the device's LAGs when absent. */
+    /** Number, on platforms where a LAG has a number instead of a name. Its position among the device's LAGs when absent. */
     id?: number;
 };
 /** A GRE tunnel. */

package/dist/types/schema/policy.d.ts

@@ -15,7 +15,7 @@ export type PrefixSet = {
         family: Family;
     };
 };
-/** Conditions on a route. All must hold. An empty match holds for every route. */
+/** Conditions on a route. All must be true. An empty match is true for every route. */
 export type Match<S extends string> = {
     /** Only routes of this family. */
     family?: Family;
@@ -35,9 +35,9 @@ export type Match<S extends string> = {
     };
     /** The route's origin validation state. */
     rpki?: "valid" | "invalid" | "not-found";
-    /** Carries this standard community, `asn:value`. */
+    /** Has this standard community, `asn:value`. */
     community?: string;
-    /** Carries this large community, `asn:function:parameter`. */
+    /** Has this large community, `asn:function:parameter`. */
     large_community?: string;
 };
 /** Changes to a route. In community lists to remove, `*` stands for any value of a field, as in `64500:*:*`. */

package/dist/types/schema/routing.d.ts

@@ -1,5 +1,5 @@
 import type { Family, IP, Prefix, Secret } from "./common";
-/** A route the device carries without learning it. */
+/** A route the device has without learning it. */
 export type StaticRoute<I extends string, F extends string> = {
     /** Destination. */
     prefix: Prefix;
@@ -11,7 +11,7 @@ export type StaticRoute<I extends string, F extends string> = {
     blackhole?: true;
     /** Preference against other routes to the same prefix. Lower wins. 1 when absent. */
     distance?: number;
-    /** The VRF the route belongs to. The default table when absent. */
+    /** The VRF the route is in. The default table when absent. */
     vrf?: F;
     /** Why the route exists. */
     description?: string;
@@ -20,7 +20,7 @@ export type StaticRoute<I extends string, F extends string> = {
  * What a BGP neighbor is to us, with the roles RFC 9234 defines: `provider`, a transit we buy from; `customer`, one we sell transit to; `peer`, one we exchange our own routes with; `rs`, an exchange's route server; `rs-client`, a network using our route server.
  */
 export type BgpRole = "provider" | "customer" | "peer" | "rs" | "rs-client";
-/** Settings a BGP neighbor can state itself or take from its group. */
+/** Settings a BGP neighbor can set itself or take from its group. */
 export type NeighborSettings<P extends string> = {
     /** The neighbor's AS. Our own AS makes the session internal. */
     remote_as?: number;
@@ -32,7 +32,7 @@ export type NeighborSettings<P extends string> = {
     import?: P;
     /** Policy for routes announced. Nothing is announced when absent. */
     export?: P;
-    /** What the neighbor is to us, such as `provider` for a transit. Both sides then reject a route leak, after RFC 9234. */
+    /** What the neighbor is to us, such as `provider` for a transit. Both sides then reject a route leak, as RFC 9234 describes. */
     role?: BgpRole;
     /** The neighbor is more than one hop away. */
     multihop?: boolean;
@@ -51,11 +51,11 @@ export type NeighborSettings<P extends string> = {
     /** Detect a dead link in under a second with BFD. */
     bfd?: boolean;
 };
-/** One BGP session. Settings it does not state come from its group. */
+/** One BGP session. Settings it does not set come from its group. */
 export type Neighbor<P extends string, G extends string> = NeighborSettings<P> & {
     /** The neighbor's address. */
     address: IP;
-    /** Group whose settings this neighbor takes where it states none. */
+    /** The group this neighbor takes a setting from when it does not set that setting itself. */
     group?: NoInfer<G>;
 };
 /** BGP on this device. */
@@ -104,7 +104,7 @@ export type Ospf<I extends string> = {
 export type Routing<P extends string, G extends string, I extends string, F extends string> = {
     /** Identifies this router to its neighbors. */
     router_id?: IP;
-    /** Routes the device carries without learning them. */
+    /** Routes the device has without learning them. */
     static?: readonly StaticRoute<I, F>[];
     /** BGP sessions and what they exchange. */
     bgp?: Bgp<P, G>;

package/dist/types/schema/system.d.ts

@@ -12,7 +12,7 @@ export type System = {
         /** Answer queries from others. Off when absent. */
         serve?: boolean;
     };
-    /** Time the device keeps. */
+    /** How the device keeps time. */
     ntp?: {
         /** Time sources, by address or name. */
         servers: readonly string[];
@@ -82,7 +82,7 @@ export type SnmpUser = {
 };
 /** How the device is reached and managed. */
 export type Management<I extends string, C extends string> = {
-    /** Sources allowed to every service that does not state its own. */
+    /** Sources allowed to every service that does not set its own. */
     allow?: readonly Prefix[];
     /** Secure shell. */
     ssh?: Service & {
@@ -139,11 +139,11 @@ export type DhcpServer<I extends string> = {
     interface: I;
     /** The network it serves. */
     network: Prefix;
-    /** Default gateway handed out. */
+    /** Default gateway given to clients. */
     gateway: IP;
-    /** Resolvers handed out. */
+    /** Resolvers given to clients. */
     dns?: readonly IP[];
-    /** First and last address handed out. */
+    /** First and last address given to clients. */
     pool: readonly [IP, IP];
     /** Seconds a lease lasts. */
     lease_time?: number;
@@ -164,9 +164,9 @@ export type DhcpRelay<I extends string> = {
 };
 /** A certificate the device presents or trusts. */
 export type Certificate = {
-    /** The certificate, PEM. Public, so it lives in the repository. */
+    /** The certificate, PEM. Public, so it is kept in the repository. */
     certificate: string;
-    /** Its private key: a PEM file through `secretFile`, or PEM base64-encoded as one line through `secret`. A certificate only trusted, such as a CA, has none. */
+    /** Its private key: a PEM file through `secretFile`, or PEM base64-encoded as one line through `secret`. A certificate the device only trusts, such as a CA, has none. */
     private_key?: Secret;
 };
 /** Export flow records or packet samples to collectors. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.26.0",
+    "version": "0.26.1",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",

package/src/adapters/devices/fortios/TRAPS.md

@@ -5,32 +5,32 @@ Behaviour that looks like something else. Each one has been hit on a FortiGate 3
 - A change applies at `next` or `end`, and with `cfg-save automatic`, the factory setting, it is saved at once. `abort` discards the changes of the one object being edited, and only there: inside a table it is `Unknown action 0`, and the entries already left with `next` are applied.
 - `cfg-save revert` keeps changes running but unsaved, and `cfg-revert-timeout` seconds after a change the device announces `System will reload` and reloads its saved configuration. The reload restarts the configuration, not the hardware, and takes about two minutes. `execute cfg reload` does the same at once, without asking, and says `no config to be reloaded` when nothing is unsaved. `execute cfg save` saves; setting `cfg-save automatic` again saves too.
 - `cfg-save revert` set while saving is automatic is saved itself. After a reload the device is still in revert mode, and from then on every change made by hand is undone after the timeout until someone saves it or sets `cfg-save automatic`. Circuit sets it back at the end of every apply.
-- `execute config-transaction start N` opens a candidate that `commit` applies and `abort` discards, but Circuit does not use it on 6.2.2. Inside one, deleting an entry does not release what its lists name, so deleting a policy and then the address it named is refused: `The entry is used by other 1 entries`. A transaction whose session is cut off keeps every object it touched locked until its N minutes run out: `Can not config the object since it's being configured by another transaction`. Editing a `firewall policy6` entry after `unset central-nat` ends the session at `edit`. Deleting the user you are logged in as ends the session with `cmdb_txn_cache_data ... failed` and breaks every later transaction until the device restarts. `show` prints a new static route or policy with the comment of the last new one, which the commit corrects. OSPF's `config redistribute` is refused, `config child object 'redistribute' is not handled in transaction`, and a certificate added in one cannot be named until the commit. None of these happen outside a transaction.
+- `execute config-transaction start N` opens a candidate that `commit` applies and `abort` discards, but Circuit does not use it on 6.2.2. Inside one, deleting an entry does not release what its lists point to, so deleting a policy and then the address it used is refused: `The entry is used by other 1 entries`. A transaction whose session is cut off keeps every object it touched locked until its N minutes run out: `Can not config the object since it's being configured by another transaction`. Editing a `firewall policy6` entry after `unset central-nat` ends the session at `edit`. Deleting the user you are logged in as ends the session with `cmdb_txn_cache_data ... failed` and breaks every later transaction until the device restarts. `show` prints a new static route or policy with the comment of the last new one, which the commit corrects. OSPF's `config redistribute` is refused, `config child object 'redistribute' is not handled in transaction`, and a certificate added in one cannot be used by name until the commit. None of these happen outside a transaction.
 - The CLI pages long output with `--More--`, and erases the prompt with spaces and a carriage return once it is answered.
 - A `?` typed anywhere shows help at once and is never sent. Ctrl-V before it types it literally.
 - The idle timeout, `admintimeout`, is 5 minutes by default; the session then returns to `login:`.
 - With `pre-login-banner` on, the console shows the banner and waits on `(Press 'a' to accept):` before `login:`. Circuit answers `a`.
 - `grep` after a pipe takes no `-E`, and a command ending in `| grep` reports `Command fail. Return code -27` after printing its matches.
 - `show` prints a setting only when it differs from its default, and prints keys in its own order, not the order they were set. A new aggregate is given `device-identification enable` and `lldp-transmission enable`, a new VLAN interface `device-identification enable` and `role lan`, without being asked. Circuit unsets them.
-- A port joins an aggregate only while nothing names it, such as a static route, `entry not found in datasource`, and its speed cannot change while it is in one, not even back to `auto`: `Interface speed cannot be set for aggregated interfaces`. Circuit frees ports first: what names a port that joins is deleted and created again after, a port whose speed changes leaves its aggregate and joins again, and an aggregate that goes, or is left with no port, goes before anything else with what names it.
+- A port joins an aggregate only while nothing points to it, such as a static route, `entry not found in datasource`, and its speed cannot change while it is in one, not even back to `auto`: `Interface speed cannot be set for aggregated interfaces`. Circuit frees ports first: what points to a port that joins is deleted and created again after, a port whose speed changes leaves its aggregate and joins again, and an aggregate that goes, or is left with no port, goes before anything else with what points to it.
 - `unset secondary-IP` hides the list of secondary addresses and drops it. NTP's `unset type` hides its servers but keeps them: `set type custom` brings them back. NTP refuses to delete its last server while `ntpsync` is on, and to empty the interfaces it serves on while `server-mode` is on, `There aren't any interfaces with NTP server enabled`; `unset server-mode` hides that list and lets go of the interfaces in it. The plan deletes a nested list before the setting that hides it, except `ntpsync`, which goes first.
-- A DHCP server prints `dns-server1` only while `dns-service` is `specify`, the default, which `show` does not print. The factory server on `mgmt1` uses `default`, so the render states `specify` before its resolvers.
+- A DHCP server prints `dns-server1` only while `dns-service` is `specify`, the default, which `show` does not print. The factory server on `mgmt1` uses `default`, so the render writes `specify` before its resolvers.
 - The timezone is a number of the platform's own, such as `53` for Jakarta, Bangkok and Hanoi. The default is `00`, Eniwetok, at UTC+12; UTC is `80`.
 - Global `alias` is set again at every start, whatever was saved.
 - `log memory setting` prints its `status` whether on or off, and `unset status` turns memory logging on.
-- Two interfaces that are up cannot hold overlapping subnets, `Subnets overlap between ...`, so an address moving from one to another must leave the first before it joins the second.
+- Two interfaces that are up cannot have overlapping subnets, `Subnets overlap between ...`, so an address moving from one to another must leave the first before it joins the second.
 - A static route identical to another is refused, `Duplicated entry`. An IPv4 route's destination is not printed when it is the default route; neither is IPv6's.
-- A deny policy is given `logtraffic disable`, and its action is not printed, since deny is the default. `send-deny-packet` exists only while a policy denies: set before `action deny` or unset after `action accept`, it is `command parse error`. The render states `action deny`, and the plan undoes what goes before it sets what comes.
-- `show` prints `unset` in two places: an ICMP service's `unset icmptype`, and a prefix list rule's `unset ge` and `unset le` for a bound it does not hold.
+- A deny policy is given `logtraffic disable`, and its action is not printed, since deny is the default. `send-deny-packet` exists only while a policy denies: set before `action deny` or unset after `action accept`, it is `command parse error`. So the render writes `action deny` before `send-deny-packet`, and a plan removes the settings that go before it sets the ones that come: `send-deny-packet` is unset while the policy still denies, and set only once it does.
+- `show` prints `unset` in two places: an ICMP service's `unset icmptype`, and a prefix list rule's `unset ge` and `unset le` for a bound it does not have.
 - An SNMPv3 user authenticates with MD5 or SHA1 only, and has no list of sources: only a community has hosts. Circuit decides who reaches every service with local-in policies instead.
 - The console ignores a user's trusted hosts.
 - A tunnel's interface takes an IPv4 address only as a host, with the far end in `remote-ip`: `set ip 10.0.0.1 255.255.255.252` on one is dropped without a word.
-- A GRE or VXLAN tunnel creates an interface of its own, named after it, which goes when the tunnel goes. VXLAN has no local address: it leaves from the address of the interface it names.
+- A GRE or VXLAN tunnel creates an interface of its own, named after it, which goes when the tunnel goes. VXLAN has no local address: it leaves from the address of the interface it points to.
 - A static route has no VRF of its own. It lands in the VRF of the interface it leaves through, as `get router info routing-table all` shows, so a blackhole route cannot go in a VRF. OSPF and BGP have no VRF setting.
 - The stateless ACL, `firewall acl` and `acl6`, only drops: it has no action.
 - A route map stops at the first rule that matches, with no way to go on to the next, and its rules permit unless told to deny.
 - `show vpn certificate local` prints a certificate without its text or key. `show full-configuration` prints both, the key encrypted.
-- A private key the device cannot read is answered `Invalid private key, password may be required`, with no `Command fail`, and the session goes on, as it is for one whose lines end in CR LF: the CLI takes each CR as a line of its own; the certificate fails only at `end`, `Attribute 'private-key' MUST be set`.
+- The device answers a private key it cannot read with `Invalid private key, password may be required`, with no `Command fail`, and the session goes on. A key whose lines end in CR LF gets the same answer, because the CLI takes each CR as a line of its own. The certificate fails only at `end`: `Attribute 'private-key' MUST be set`.
 - A GRE or VXLAN interface takes no flow sampler, and says so without `Command fail`: `Netflow sampler isn't supported on Tunnel interface..`, and the same for sFlow and for VXLAN.
 - A port in an aggregate has no `icmp-send-redirect`, `command parse error`, and loses it when it joins one.
 - `purge` empties a table after asking `(y/n)`.

package/src/adapters/devices/junos/TRAPS.md

@@ -17,10 +17,10 @@ Behaviour that looks like something else. Each one has been hit on a QFX5100-48S
 - An SNMP community prints in clear, and its value is also its name, so a new value is a second community. A new value is sent after the old communities are deleted, each by its name, which Circuit looks up during the apply and never prints.
 - A firewall filter name is unique across families. The filter guarding the device's services is `circuit-services` for IPv4 and `circuit-services-v6` for IPv6.
 - A VLAN interface's MTU above what its ports carry commits with only a warning, `mtu 9000 is bigger than member link`.
-- There is no `protocols stp`. Plain STP is RSTP held back with `force-version stp`.
+- There is no `protocols stp`. Plain STP is RSTP limited with `force-version stp`.
 - sFlow interfaces print with their unit, `xe-0/0/0.0`.
 - The factory VLAN `default` can be deleted.
-- BGP without a licence commits with only a warning, `requires 'bgp' license`, and sessions establish. The same holds for the other licensed features.
+- BGP without a licence commits with only a warning, `requires 'bgp' license`, and sessions establish. The same is true for the other licensed features.
 - Junos accepts and announces every route over eBGP unless a policy says otherwise: `Default eBGP mode: advertise - accept, receive - accept`. A session without a policy is given `circuit-reject-all`.
 - An export policy sees every active route, not only BGP's. Every export starts with `circuit-bgp-origin`, which passes on BGP's routes and the prefixes in `routing.bgp.networks` and rejects the rest.
 - A policy's or a filter's terms are kept in order, and `set` adds a new term at the end. A change to one rewrites it whole.

package/src/adapters/devices/raisecom-ros/TRAPS.md

@@ -6,7 +6,7 @@ Behaviour that looks like something else. Each one has been hit on a RAX721 runn
 - The SSH server offers only an `ssh-rsa` host key. The adapter allows it for this platform alone; key exchange, cipher and MAC still negotiate modern ones.
 - `show running-config` stops about halfway with no error unless `terminal page-break disable` is sent first and the read waits several seconds of silence.
 - A `?` sent by a script is executed. Once it applied an address with a /8 mask.
-- An access-list cannot change while any service holds it: `ACL 1000 is in use`. Every holder is released first and bound again after. `no ssh2 access-list` needs the list number.
+- An access-list cannot change while any service uses it: `ACL 1000 is in use`. Every service that uses it is unbound first and bound again after. `no ssh2 access-list` needs the list number.
 - `portswitch`, `switchport trunk allowed vlan` and `switchport mode` ask for `y` and do nothing without it, except when they need no confirming: `switchport mode trunk` on a port leaving access mode answers `Set successfully` at once, and a `y` sent after it is refused, `Error input`.
 - A VLAN is removed with `no vlan <id>`, not `no create vlan`.
 - The factory account `raisecom` cannot be removed and its service type cannot change. Only its password is ours.
@@ -18,5 +18,5 @@ Behaviour that looks like something else. Each one has been hit on a RAX721 runn
 - An SNMPv3 user prints as localized keys, `authkey sha <hex> privkey  aes128 <hex>`, which authenticate as well as the passphrase. The read redacts them. An access group prints a `notify internet` it was not given. A user's group is removed with `no snmp-server group user <user> usm`.
 - A VRRP group is enabled once it has an address and preempts unless `no vrrp N preempt`. `no vrrp N ip <address>` removes the whole group.
 - OSPF settings for an interface sit on the interface, `ip ospf cost`, `ip ospf network ptp`, `ip ospf passive-interface enable`; passive is undone with `... disable`, not `no`.
-- `create vlan <list> active` holds every VLAN on one line. A change creates only the new VLANs and removes each gone one with `no vlan <id>`.
+- `create vlan <list> active` has every VLAN on one line. A change creates only the new VLANs and removes each one that is gone with `no vlan <id>`.
 - An access-list rule is not replaced by one with the same number: the device answers `Set unsuccessfully.` and keeps the old rule. The old one is removed first. `no rule N` answers slowly, after a second or more.

package/src/adapters/devices/routeros/TRAPS.md

@@ -3,11 +3,11 @@
 Behaviour that looks like something else. Each one has been hit on a real device.
 
 - Every command takes effect as it arrives; there is no candidate configuration. `apply` saves a backup, arms a scheduler that restores it, and restores at once if a command is refused.
-- A `/32` address gives no connected route, so a session over it never opens. State the far end: `{ address, peer }` renders `network=<peer>`.
+- A `/32` address gives no connected route, so a session over it never opens. Give the far end: `{ address, peer }` renders `network=<peer>`.
 - `[find address=X/Y]` unquoted matches nothing, silently. Every selector the plan builds is quoted.
 - `~` in `find` has no anchors. Match exactly.
 - A property of the same group is printed as a bare suffix, `output.filter-chain=X .network=Y`, which only reads back inside that command. The parser expands it before building a `set`.
-- `/routing bgp connection add` without `local.role` is refused, so the render always states one. On 7.23 one without `instance` is refused too, `missing value(s) of argument(s) instance`, although the export never prints `instance=default`.
+- `/routing bgp connection add` without `local.role` is refused, so the render always writes one. On 7.23 one without `instance` is refused too, `missing value(s) of argument(s) instance`, although the export never prints `instance=default`.
 - A connection without `input.filter` accepts everything. A neighbor without a policy is given `REJECT-ALL`.
 - A session edited repeatedly can stick: SYN both ways, no RST, no log. Remove the connection and add it again.
 - A session that never established is missing from `/routing bgp session print`; look at `/routing bgp connection print`.
@@ -27,17 +27,17 @@ Behaviour that looks like something else. Each one has been hit on a real device
 - `mac-server` and `mac-winbox` work at layer 2 and ignore the IP firewall; they are limited by interface list.
 - `time-zone-autodetect` is on by default and wins after a restart. The render turns it off.
 - The SSH client drops a password sent together with its newline. Send the password, wait, then the newline.
-- A serial console login redraws lines unless the user name carries `+cwt`.
+- A serial console login redraws lines unless the user name has `+cwt`.
 - Narrowing a subnet is a change in several places: the address, the DHCP network, and every switch on the LAN. A mismatch breaks only the return path, so a test from the router passes.
 - In `find`, a quoted `"yes"` is a string and matches no boolean, silently. Plain words go bare; only values with a slash or a space are quoted.
-- `:put [:parse "..."]` compiles a command without running it and names a syntax error or an unknown property. `apply` checks every command this way before the backup is taken.
+- `:put [:parse "..."]` compiles a command without running it and reports a syntax error or an unknown property. `apply` checks every command this way before the backup is taken.
 - A refused command restores the backup, which restarts the router. Expect every session to re-establish over a minute or two.
 - `strong-crypto=yes` also hardens the device's own SSH client, which then fails silently toward devices that only speak older algorithms.
 - SNMPv3 authenticates with MD5 or SHA1 only on 7.23.
 - In a quoted string `$` starts a variable. The adapter escapes it.
 - A script sent over SSH exec runs as one line; a multi-line script fails with `expected closing brace`.
 - `:find` on an array returns a number or `nil`. Globals persist between exec commands of one login.
-- A fixed port speed is named by medium, `speed=10G-baseSR-LR` for an optic or `speed=1G-baseT-full` for copper, and only holds with `auto-negotiation=no`. With auto-negotiation back on, the export no longer prints the speed, so the plan resets only auto-negotiation. `speed=""` is refused as ambiguous and `unset speed` does not exist.
+- A fixed port speed is named by medium, `speed=10G-baseSR-LR` for an optic or `speed=1G-baseT-full` for copper, and only stays set with `auto-negotiation=no`. With auto-negotiation back on, the export no longer prints the speed, so the plan resets only auto-negotiation. `speed=""` is refused as ambiguous and `unset speed` does not exist.
 - `bgp-path-len` counts every AS in the path, prepends included, and takes the same strict comparisons as `dst-len`.
 - `:parse` checks the command, not the text inside `rule=`. A routing filter rule is only checked when it is added.
 - `/routing/filter/filter-wizard` adds the rule it builds; it is not a dry run. `set blackhole yes` was proved this way on 7.23, in an unused chain removed right after.

package/src/adapters/devices/vrp/TRAPS.md

@@ -14,10 +14,10 @@ Behaviour that looks like something else. Each one has been hit on a CE6855 runn
 - LLDP is off by default. A port setting for LLDP is refused until it is on globally.
 - A trunk forwards its native VLAN's untagged frames only when that VLAN is also allowed; the adapter adds it.
 - The name `admin` is refused for a local user.
-- A port joins an Eth-Trunk only while it holds no other setting, including a description.
+- A port joins an Eth-Trunk only while it has no other setting, including a description.
 - An empty block such as `bfd` enters its view; the next line sent goes into it unless the view is left.
 - SNMPv3 passwords are asked for interactively, twice. `authentication-mode` must come before `privacy-mode`.
 - `abort` is not a command here. `clear configuration candidate` discards uncommitted changes.
-- sFlow samples per port, `sflow sampling rate N`, N from 4096; the default is 8192 and an explicit 8192 is kept as written. A port names a collector only once the collector exists globally; until then it is refused with "collector does not exist".
-- `vlan batch` holds every VLAN on one line, and undoing a list that names a VLAN with an L3 interface is refused. A change sends only the VLANs added and `undo vlan batch` for the ones removed.
-- A VLAN name is unique across VLANs: a new VLAN cannot take a name another still holds. VLANs no longer used, and their VLAN interfaces, are removed first, in the same candidate.
+- sFlow samples per port, `sflow sampling rate N`, N from 4096; the default is 8192 and an explicit 8192 is kept as written. A port can point to a collector only once the collector exists globally; until then it is refused with "collector does not exist".
+- `vlan batch` has every VLAN on one line, and undoing a list that includes a VLAN with an L3 interface is refused. A change sends only the VLANs added and `undo vlan batch` for the ones removed.
+- A VLAN name is unique across VLANs: a new VLAN cannot take a name another still has. VLANs no longer used, and their VLAN interfaces, are removed first, in the same candidate.

package/src/schema/common.ts

@@ -9,7 +9,7 @@ export type Secret =
           readonly secret: string;
       }
     | {
-          /** Path of a file holding the value, relative to the config file. */
+          /** Path of the file with the value, relative to the config file. */
           readonly secret_file: string;
       };
 

package/src/schema/device.ts

@@ -43,7 +43,7 @@ export type Device<
 > = {
     /** Hostname. */
     name: string;
-    /** Operating system, which decides the adapter that renders and applies the device. */
+    /** Operating system. It decides which adapter renders and applies the device. */
     platform: Pl;
     /** Hardware model. Decides which port names exist. */
     model: M;

package/src/schema/firewall.ts

@@ -15,7 +15,7 @@ export type Ports = number | PortRange | readonly (number | PortRange)[];
 /** A TCP header flag. */
 export type TcpFlag = "fin" | "syn" | "rst" | "psh" | "ack" | "urg";
 
-/** Conditions on a packet. All must hold. A rule with addresses of one family applies to that family only. */
+/** Conditions on a packet. All must be true. A rule with addresses of one family applies to that family only. */
 export type FilterMatch<I extends string, AS extends string> = {
     /** Only packets of this family. */
     family?: Family;
@@ -51,7 +51,7 @@ export type FilterRule<I extends string, AS extends string> = {
     match?: FilterMatch<I, AS>;
     /** What happens to a matching packet. `reject` answers the sender, `drop` does not. */
     action: "accept" | "drop" | "reject";
-    /** Hand the rest of an accepted flow to the fast path, past the remaining rules. */
+    /** Send the rest of an accepted flow through the fast path, skipping the remaining rules. */
     offload?: true;
 };
 
@@ -126,7 +126,7 @@ export type AclRule<V extends string> = {
         src_port?: Ports;
         /** Destination port, or any of several. */
         dst_port?: Ports;
-        /** Carried in this VLAN. */
+        /** In this VLAN. */
         vlan?: V;
     };
     /** What happens to a matching packet. */

package/src/schema/interfaces.ts

@@ -1,8 +1,8 @@
 import type { Address, IP, Prefix, Secret } from "./common";
 
-/** A VLAN. The key it is declared under is its name. */
+/** A VLAN. Its key in `vlans` is its name. */
 export type Vlan = {
-    /** The number carried on the wire, 1 to 4094. */
+    /** The VLAN's number on the wire, 1 to 4094. */
     id: number;
     /** What the VLAN is for. */
     description?: string;
@@ -25,7 +25,7 @@ export type Vrrp = {
     interval?: number;
 };
 
-/** Layer 3 settings shared by every interface that can hold an address. */
+/** Layer 3 settings shared by every interface that can have an address. */
 export type Routed<F extends string> = {
     /** Addresses with their length. Use `{ address, peer }` for a point-to-point address whose far end is outside its own prefix. */
     addresses?: readonly (Address | { address: Address; peer: IP })[];
@@ -33,7 +33,7 @@ export type Routed<F extends string> = {
     ipv6_ra?: boolean;
     /** Overrides the device's `hardware_offload` for traffic routed through this interface. Software forwarding is what makes the firewall apply. */
     hardware_offload?: boolean;
-    /** Virtual router addresses held on this interface. */
+    /** Virtual router addresses on this interface. */
     vrrp?: readonly Vrrp[];
     /** The VRF this interface routes in. The default table when absent. */
     vrf?: F;
@@ -63,11 +63,11 @@ export type PortStp = {
 
 /** Layer 2 membership. A port or LAG with none of these is routed. */
 export type Switched<V extends string> = {
-    /** Untagged member of one VLAN. */
+    /** The one VLAN this port or LAG is in, untagged. */
     access_vlan?: V;
-    /** Tagged member of these VLANs. */
+    /** The VLANs this port or LAG carries, tagged. */
     trunk_vlans?: readonly V[];
-    /** Untagged frames on a trunk belong to this VLAN. Only with `trunk_vlans`. */
+    /** Untagged frames on a trunk are in this VLAN. Only with `trunk_vlans`. */
     native_vlan?: V;
     /** Overrides the device's `stp` for this port. `false` stops it sending or acting on BPDUs. */
     stp?: boolean | PortStp;
@@ -100,7 +100,7 @@ export type Port<V extends string, A extends string, L extends string, F extends
         lldp?: boolean;
         /** Hardware ACL applied to traffic arriving on this port. */
         acl?: A;
-        /** Member of this LAG. The LAG holds every other setting. */
+        /** The LAG this port is in. Every other setting goes on the LAG. */
         lag?: L;
         /** Another of our devices at the other end of the cable. */
         link?: Link;
@@ -117,20 +117,20 @@ type Base<F extends string> = Routed<F> & {
 /** A layer 3 interface on a VLAN. */
 export type VlanInterface<V extends string, F extends string> = Base<F> & {
     type: "vlan";
-    /** The VLAN it sits on. */
+    /** The VLAN it is on. */
     vlan: V;
 };
 
-/** An interface that is always up and belongs to no link, for addresses that must not depend on one. */
+/** An interface that is always up and is on no link, for addresses that must not depend on one. */
 export type Loopback<F extends string> = Base<F> & { type: "loopback" };
 
-/** A link aggregation. Member ports name it with `lag`. */
+/** A link aggregation. Each member port points to it with `lag`. */
 export type Lag<V extends string, F extends string> = Base<F> &
     Switched<V> & {
         type: "lag";
-        /** LACP negotiates membership with the far end; static bundles without asking. LACP when absent. */
+        /** LACP negotiates membership with the far end; `static` joins the ports without asking. LACP when absent. */
         mode?: "lacp" | "static";
-        /** Number on platforms that name a LAG by number. Its position among the device's LAGs when absent. */
+        /** Number, on platforms where a LAG has a number instead of a name. Its position among the device's LAGs when absent. */
         id?: number;
     };
 

package/src/schema/policy.ts

@@ -20,7 +20,7 @@ export type PrefixSet =
           };
       };
 
-/** Conditions on a route. All must hold. An empty match holds for every route. */
+/** Conditions on a route. All must be true. An empty match is true for every route. */
 export type Match<S extends string> = {
     /** Only routes of this family. */
     family?: Family;
@@ -34,9 +34,9 @@ export type Match<S extends string> = {
     as_path_length?: { min?: number; max?: number };
     /** The route's origin validation state. */
     rpki?: "valid" | "invalid" | "not-found";
-    /** Carries this standard community, `asn:value`. */
+    /** Has this standard community, `asn:value`. */
     community?: string;
-    /** Carries this large community, `asn:function:parameter`. */
+    /** Has this large community, `asn:function:parameter`. */
     large_community?: string;
 };
 

package/src/schema/routing.ts

@@ -1,6 +1,6 @@
 import type { Family, IP, Prefix, Secret } from "./common";
 
-/** A route the device carries without learning it. */
+/** A route the device has without learning it. */
 export type StaticRoute<I extends string, F extends string> = {
     /** Destination. */
     prefix: Prefix;
@@ -12,7 +12,7 @@ export type StaticRoute<I extends string, F extends string> = {
     blackhole?: true;
     /** Preference against other routes to the same prefix. Lower wins. 1 when absent. */
     distance?: number;
-    /** The VRF the route belongs to. The default table when absent. */
+    /** The VRF the route is in. The default table when absent. */
     vrf?: F;
     /** Why the route exists. */
     description?: string;
@@ -23,7 +23,7 @@ export type StaticRoute<I extends string, F extends string> = {
  */
 export type BgpRole = "provider" | "customer" | "peer" | "rs" | "rs-client";
 
-/** Settings a BGP neighbor can state itself or take from its group. */
+/** Settings a BGP neighbor can set itself or take from its group. */
 export type NeighborSettings<P extends string> = {
     /** The neighbor's AS. Our own AS makes the session internal. */
     remote_as?: number;
@@ -35,7 +35,7 @@ export type NeighborSettings<P extends string> = {
     import?: P;
     /** Policy for routes announced. Nothing is announced when absent. */
     export?: P;
-    /** What the neighbor is to us, such as `provider` for a transit. Both sides then reject a route leak, after RFC 9234. */
+    /** What the neighbor is to us, such as `provider` for a transit. Both sides then reject a route leak, as RFC 9234 describes. */
     role?: BgpRole;
     /** The neighbor is more than one hop away. */
     multihop?: boolean;
@@ -55,11 +55,11 @@ export type NeighborSettings<P extends string> = {
     bfd?: boolean;
 };
 
-/** One BGP session. Settings it does not state come from its group. */
+/** One BGP session. Settings it does not set come from its group. */
 export type Neighbor<P extends string, G extends string> = NeighborSettings<P> & {
     /** The neighbor's address. */
     address: IP;
-    /** Group whose settings this neighbor takes where it states none. */
+    /** The group this neighbor takes a setting from when it does not set that setting itself. */
     group?: NoInfer<G>;
 };
 
@@ -111,7 +111,7 @@ export type Ospf<I extends string> = {
 export type Routing<P extends string, G extends string, I extends string, F extends string> = {
     /** Identifies this router to its neighbors. */
     router_id?: IP;
-    /** Routes the device carries without learning them. */
+    /** Routes the device has without learning them. */
     static?: readonly StaticRoute<I, F>[];
     /** BGP sessions and what they exchange. */
     bgp?: Bgp<P, G>;

package/src/schema/system.ts

@@ -13,7 +13,7 @@ export type System = {
         /** Answer queries from others. Off when absent. */
         serve?: boolean;
     };
-    /** Time the device keeps. */
+    /** How the device keeps time. */
     ntp?: {
         /** Time sources, by address or name. */
         servers: readonly string[];
@@ -87,7 +87,7 @@ export type SnmpUser = {
 
 /** How the device is reached and managed. */
 export type Management<I extends string, C extends string> = {
-    /** Sources allowed to every service that does not state its own. */
+    /** Sources allowed to every service that does not set its own. */
     allow?: readonly Prefix[];
     /** Secure shell. */
     ssh?: Service & {
@@ -141,11 +141,11 @@ export type DhcpServer<I extends string> = {
     interface: I;
     /** The network it serves. */
     network: Prefix;
-    /** Default gateway handed out. */
+    /** Default gateway given to clients. */
     gateway: IP;
-    /** Resolvers handed out. */
+    /** Resolvers given to clients. */
     dns?: readonly IP[];
-    /** First and last address handed out. */
+    /** First and last address given to clients. */
     pool: readonly [IP, IP];
     /** Seconds a lease lasts. */
     lease_time?: number;
@@ -168,9 +168,9 @@ export type DhcpRelay<I extends string> = {
 
 /** A certificate the device presents or trusts. */
 export type Certificate = {
-    /** The certificate, PEM. Public, so it lives in the repository. */
+    /** The certificate, PEM. Public, so it is kept in the repository. */
     certificate: string;
-    /** Its private key: a PEM file through `secretFile`, or PEM base64-encoded as one line through `secret`. A certificate only trusted, such as a CA, has none. */
+    /** Its private key: a PEM file through `secretFile`, or PEM base64-encoded as one line through `secret`. A certificate the device only trusts, such as a CA, has none. */
     private_key?: Secret;
 };