@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/mysql-patterns/references/online-ddl.md

@@ -0,0 +1,41 @@
+# MySQL online DDL
+
+Always name the algorithm and lock level so the server errors instead of silently falling back to a blocking table copy:
+
+```sql
+ALTER TABLE orders ADD COLUMN note VARCHAR(200) NULL, ALGORITHM=INSTANT;
+ALTER TABLE orders ADD INDEX orders_status_idx (status, created_at), ALGORITHM=INPLACE, LOCK=NONE;
+```
+
+## What the InnoDB online DDL table says (MySQL 8.4 manual)
+
+| Change | Algorithm | Concurrent DML |
+|---|---|---|
+| Add column (any position) | INSTANT (default) | yes |
+| Drop column | INSTANT (default) | yes |
+| Add secondary index | INPLACE, no rebuild | yes |
+| Drop index | INPLACE | yes |
+| Extend `VARCHAR` within the same length-prefix size (both under 256 bytes, or both 256+) | INPLACE | yes |
+| Extend `VARCHAR` across 255 to 256+ bytes, or shrink it | COPY | no |
+| Change column data type (for example `INT` to `BIGINT`) | COPY | no |
+| Convert table character set (`CONVERT TO CHARACTER SET`) | COPY (rebuild) | no |
+
+Limits on INSTANT: not for `ROW_FORMAT=COMPRESSED` tables, tables with a `FULLTEXT` index, temporary tables or tables in the data dictionary tablespace. Each instant add or drop creates a row version; when the per-table limit is reached (64 in 8.4, 255 as of MySQL 9.1) instant changes fail with error 4092 and the table must be rebuilt. Check `INFORMATION_SCHEMA.INNODB_TABLES.TOTAL_ROW_VERSIONS`.
+
+MariaDB has its own instant and online rules; check its `ALTER TABLE` and InnoDB online DDL docs for the server version.
+
+Source: https://dev.mysql.com/doc/refman/8.4/en/innodb-online-ddl-operations.html
+
+## Metadata locks
+
+Even INSTANT and INPLACE DDL need a brief exclusive metadata lock at start and end. If a long transaction holds a shared metadata lock on the table, the `ALTER` waits, and every new query on the table queues behind it. Before DDL:
+
+```sql
+SET SESSION lock_wait_timeout = 5;   -- seconds to wait for the metadata lock
+```
+
+Check for long transactions first: `SELECT * FROM information_schema.innodb_trx ORDER BY trx_started;`.
+
+## When to use an external tool
+
+Use `gh-ost` or `pt-online-schema-change` when the change needs COPY on a large, busy table (type changes, charset conversion). Both build a shadow table, copy rows in chunks with replica-lag throttling, then swap. They need a primary key or unique key, extra disk for a full copy, and testing on staging first. `pt-online-schema-change` uses triggers; `gh-ost` reads the binary log (row format) instead.

package/skills/nestjs-patterns/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: nestjs-patterns
+description: NestJS application structure and conventions, covering feature modules, providers and dependency-injection scopes, ValidationPipe with class-validator DTOs, guards, interceptors, exception filters, ConfigModule, database modules (TypeORM, Prisma, Mongoose) and Test.createTestingModule unit and e2e tests. Use when building or restructuring a NestJS API, wiring a new module or provider, fixing a circular dependency or "Nest can't resolve dependencies" error, adding auth guards, or writing NestJS tests.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node.js and the project's package manager. Check the project's @nestjs/core major version and its migration guide before using version-specific APIs.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# NestJS patterns
+
+Keep a Nest app boring: one feature per module, thin controllers, logic in providers, validation at the edge, and tests that swap providers instead of patching imports.
+
+## First, look at the project
+
+1. Read `package.json` for the `@nestjs/core` major, the HTTP adapter (`@nestjs/platform-express` or `@nestjs/platform-fastify`) and the ORM.
+2. Read `src/main.ts` and `src/app.module.ts` to see global pipes, filters, prefixes and versioning already set.
+3. Match existing conventions (folder layout, DTO library, error shape). Do not introduce a second ORM, validation library or config style.
+
+Stop and ask the user before switching HTTP adapter, ORM, or moving from class-validator to a schema library: these touch every module.
+
+## Module layout
+
+```
+src/
+  main.ts
+  app.module.ts
+  orders/
+    orders.module.ts
+    orders.controller.ts      # HTTP only: route, DTO in, DTO out
+    orders.service.ts         # business rules
+    orders.repository.ts      # optional: data access behind an injectable
+    dto/create-order.dto.ts
+    orders.service.spec.ts
+```
+
+Rules:
+
+- A module exports only the providers other modules need. Everything else stays private.
+- Import a module to use its exported providers; never list another module's provider in your own `providers` array (that creates a second instance).
+- Use `@Global()` only for true cross-cutting infrastructure (config, logger, database). Feature modules are never global.
+- Controllers never touch the ORM directly.
+- Use the CLI to scaffold (`nest g resource orders`) when the project already uses it.
+
+## Providers and scopes
+
+| Scope | Lifetime | Use for |
+|---|---|---|
+| `Scope.DEFAULT` | one instance per app | almost everything |
+| `Scope.REQUEST` | one per request | per-request tenant or user context you cannot pass as an argument |
+| `Scope.TRANSIENT` | one per consumer | stateful helpers each consumer must own, such as a logger with a context name |
+
+- Request scope bubbles up: anything that injects a request-scoped provider becomes request-scoped too, which costs performance. Prefer passing the user or tenant as a method argument, or use `AsyncLocalStorage` (for example via `nestjs-cls`).
+- Custom providers: `useValue` for constants and test doubles, `useClass` for swapping implementations, `useFactory` with `inject: [...]` for config-driven construction. Use a string or symbol token plus `@Inject(TOKEN)` for non-class dependencies.
+- **"Nest can't resolve dependencies of X (?)"**: the `?` position names the missing dependency. Check, in order: the provider is in the module's `providers` or imported from a module that `exports` it; the import is not a type-only import (`import type` erases the token); there is no circular file import producing `undefined`.
+- **Circular dependency**: first try to extract the shared logic into a third provider. Use `forwardRef(() => OtherModule)` / `@Inject(forwardRef(() => OtherService))` only when the cycle is genuine, and say so in a comment.
+
+## Request pipeline
+
+Order for each request: middleware, guards, interceptors (before), pipes, handler, interceptors (after), exception filters (on error).
+
+- **Validation**: register one global pipe in `main.ts`:
+
+  ```ts
+  app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));
+  ```
+
+  `whitelist` strips unknown properties, `forbidNonWhitelisted` rejects them, `transform` turns the payload into the DTO class and converts primitive params. DTOs are classes (interfaces vanish at runtime) decorated with `class-validator`; nested objects need `@ValidateNested()` plus `@Type(() => Child)` from `class-transformer`.
+- **Params**: use `ParseIntPipe`, `ParseUUIDPipe`, `ParseEnumPipe` on `@Param`/`@Query` instead of manual parsing.
+- **Guards** answer "may this request run?" (`CanActivate`). Read route metadata with `Reflector` (for example a `@Roles()` or `@Public()` decorator). Register auth guards globally with `{ provide: APP_GUARD, useClass: AuthGuard }` so new routes are protected by default, and opt out with `@Public()`.
+- **Interceptors** wrap the handler (`NestInterceptor`, RxJS `next.handle().pipe(...)`): response mapping, timing, caching, timeouts. They are not for authorization.
+- **Exception filters**: throw built-in `HttpException` subclasses (`NotFoundException`, `ConflictException`) from services only when the service is HTTP-specific; otherwise throw domain errors and map them to HTTP in one `@Catch(DomainError)` filter. Register with `APP_FILTER` so it can inject providers. Never leak stack traces or ORM messages in the response body.
+
+## Configuration
+
+- `ConfigModule.forRoot({ isGlobal: true, validationSchema })` once in `AppModule`; validate env at boot so a missing variable fails startup, not the first request. The accepted schema libraries vary by major version; check the config docs for the installed version.
+- Read values with `configService.getOrThrow<string>('DATABASE_URL')`. Group related settings with `registerAs('db', () => ({ ... }))` and inject the typed namespace.
+- Never read `process.env` scattered through services.
+
+## Database integration
+
+- Use the official module for the chosen ORM (`TypeOrmModule.forRootAsync`, `MongooseModule.forRootAsync`) with `useFactory` + `inject: [ConfigService]`, or a small `PrismaService` that extends `PrismaClient` and connects in `onModuleInit`.
+- Register entities or models per feature module (`TypeOrmModule.forFeature([Order])`).
+- Wrap multi-write operations in a transaction from the ORM; do not rely on sequential awaits.
+- Never use TypeORM `synchronize: true` outside local development; use migrations.
+
+## Lifecycle and shutdown
+
+- Call `app.enableShutdownHooks()` in `main.ts` so `onModuleDestroy` / `beforeApplicationShutdown` / `onApplicationShutdown` run on SIGTERM; close pools and consumers there.
+- Hooks run in module dependency order; do not depend on ordering between unrelated modules.
+
+## Testing
+
+Follow `references/testing.md` for unit and e2e templates. The rules:
+
+1. Unit-test services with `Test.createTestingModule({ providers: [OrdersService, { provide: OrdersRepository, useValue: fakeRepo }] })`.
+2. E2E-test through HTTP: build the real `AppModule`, `.overrideProvider(...)` only external services, and apply the same global pipes/filters as `main.ts` (extract a `configureApp(app)` function and call it in both places).
+3. Close the app in `afterAll` (`await app.close()`) or the test runner hangs.
+
+## Never
+
+- Put business logic in controllers, guards or interceptors.
+- Use `any`-typed `@Body() body` without a DTO.
+- Make a provider request-scoped "just in case".
+- Catch an exception in a controller only to rethrow a generic 500.
+- Disable `whitelist` to silence a validation error; fix the DTO.
+
+## Before you finish
+
+Run the project's build (`nest build` or `tsc --noEmit`), lint and test commands. Report: modules or providers added or changed, any new global pipe/guard/filter, any env variable the user must set, and test results.

package/skills/nestjs-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Nest can't resolve dependencies of the OrdersService (?), please fix it",
+    "Add a global JWT guard to our NestJS API with a @Public() decorator to opt out",
+    "Set up a ValidationPipe so our Nest DTOs reject unknown fields",
+    "Write an e2e test for the users module in NestJS that overrides the email provider",
+    "How should I split this NestJS app into feature modules with a shared Prisma service?"
+  ],
+  "should_not_trigger": [
+    "Add graceful shutdown and pino logging to our plain Express server",
+    "Design the REST resource naming and pagination for our public API",
+    "Write a Prisma migration that adds a status column to orders",
+    "Review this TypeScript pull request for type safety problems",
+    "Our Vite dev server can't find env variables in the React app"
+  ]
+}

package/skills/nestjs-patterns/references/testing.md

@@ -0,0 +1,68 @@
+# NestJS test templates
+
+Use the project's existing runner (Jest is the CLI default; Vitest needs SWC or a decorator-aware transform because Nest relies on `emitDecoratorMetadata`).
+
+## Unit test a service
+
+```ts
+import { Test } from '@nestjs/testing';
+import { OrdersService } from './orders.service';
+import { OrdersRepository } from './orders.repository';
+
+describe('OrdersService', () => {
+  let service: OrdersService;
+  const repo = { findById: jest.fn(), save: jest.fn() };
+
+  beforeEach(async () => {
+    const moduleRef = await Test.createTestingModule({
+      providers: [OrdersService, { provide: OrdersRepository, useValue: repo }],
+    }).compile();
+    service = moduleRef.get(OrdersService);
+    jest.clearAllMocks();
+  });
+
+  it('rejects an order for a missing customer', async () => {
+    repo.findById.mockResolvedValue(null);
+    await expect(service.place({ customerId: 'c1', items: [] })).rejects.toThrow('customer');
+  });
+});
+```
+
+- For request- or transient-scoped providers use `await moduleRef.resolve(Token)` instead of `get`.
+- Test guards directly: construct with a fake `Reflector` and pass a hand-built `ExecutionContext` (`switchToHttp().getRequest()` returning a plain object).
+
+## E2E test through HTTP
+
+```ts
+import { Test } from '@nestjs/testing';
+import { INestApplication } from '@nestjs/common';
+import request from 'supertest';
+import { AppModule } from '../src/app.module';
+import { configureApp } from '../src/configure-app'; // same pipes/filters/prefix as main.ts
+import { PaymentsClient } from '../src/payments/payments.client';
+
+describe('Orders (e2e)', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({ imports: [AppModule] })
+      .overrideProvider(PaymentsClient)
+      .useValue({ charge: async () => ({ id: 'ch_test', status: 'succeeded' }) })
+      .compile();
+    app = moduleRef.createNestApplication();
+    configureApp(app);
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('rejects unknown fields', () =>
+    request(app.getHttpServer()).post('/orders').send({ items: [], admin: true }).expect(400));
+});
+```
+
+- With the Fastify adapter, create the app with `createNestApplication<NestFastifyApplication>(new FastifyAdapter())` and call `await app.getHttpAdapter().getInstance().ready()` after `init()`.
+- Point e2e tests at a disposable database (container or schema per run); never at a shared dev database.
+- Other override helpers: `overrideGuard`, `overrideInterceptor`, `overridePipe`, `overrideFilter`, `overrideModule`.

package/skills/network-automation/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: network-automation
+description: Automates configuration of routers, switches and firewalls with Netmiko, NAPALM, Nornir or Ansible network collections, building a source-of-truth inventory, idempotent templates and resource modules, dry runs that show a diff before any push, commit-confirm style rollback, vaulted credentials, and testing against a containerlab or CML lab before production. Use when writing or fixing a Python or Ansible script that pushes config to many network devices, choosing between these tools, adding a check-mode diff or automatic revert to a device rollout, or moving device passwords out of an inventory file.
+license: MIT
+compatibility: Any Agent Skills host. Needs Python 3 with netmiko, napalm or nornir, or ansible-core with the vendor collection (for example cisco.ios), plus SSH reach to a lab or devices.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: network
+  kete-loom/requires: "python3"
+  kete-loom/owner: "Kete-org"
+---
+
+# Network automation
+
+Push configuration to network devices so that every run shows its diff first, does nothing when nothing changed, can be undone without console access, and never leaks a credential.
+
+For per-tool code shapes (inventory files, tasks, playbooks), read `references/tool-snippets.md`.
+
+## 0. Before you start
+
+1. Find what exists: search the repo for `inventory/`, `hosts.yaml`, `group_vars/`, `ansible.cfg`, `config.yaml` (Nornir), `requirements.txt`, Jinja2 templates (`*.j2`), and any NetBox or Nautobot URL.
+2. Ask the user, if not stated:
+   - Which platforms and OS versions (`ios`, `iosxe`, `nxos`, `eos`, `junos`, `iosxr`)? Behaviour differs per driver.
+   - Is there a lab (containerlab, Cisco Modeling Labs, GNS3, EVE-NG) or only production?
+   - What is the change window, and who approves a production push?
+3. **Stop and ask** before running anything against a production device. Default target is the lab or one named canary device.
+
+## 1. Pick the tool
+
+| Situation | Use |
+|---|---|
+| A few show commands or a one-off push, any vendor with SSH | Netmiko (`ConnectHandler`, `send_command`, `send_config_set`) |
+| Diff before push, merge or full replace, commit and rollback across vendors | NAPALM (`load_merge_candidate`, `load_replace_candidate`, `compare_config`, `commit_config`, `rollback`) |
+| Python, many devices in parallel, inventory filtering | Nornir with `nornir_napalm` / `nornir_netmiko` |
+| Team already on Ansible, declarative desired state | Ansible with `ansible.netcommon.network_cli` and vendor resource modules (`cisco.ios.ios_vlans`, `ios_interfaces`, `ios_l3_interfaces` ...) |
+
+Prefer what the repo already uses. Do not add a second framework for one task.
+
+## 2. Inventory and source of truth
+
+1. One inventory: hosts with `platform`/`ansible_network_os`, management IP, site and role. Group variables hold shared settings; hosts hold only what differs.
+2. If NetBox or Nautobot exists, read the inventory from it (the `nornir-netbox` package's `NetBoxInventory2` plugin, or Ansible's `netbox.netbox.nb_inventory`) instead of copying data into YAML.
+3. Intended config is data plus templates. Variables in YAML, rendering in Jinja2, no hand-edited per-device files.
+
+## 3. Secrets
+
+- Never put passwords, enable secrets, SNMP communities or API tokens in inventory, templates, playbooks or git history.
+- Use `ansible-vault` (`ansible-vault encrypt_string`), environment variables read at runtime, or the team's secret manager. Nornir: set `username`/`password` in a transform function from `os.environ`.
+- Mark Ansible tasks that handle secrets with `no_log: true`. Do not print rendered configs that contain secrets; redact before logging diffs.
+- If you find a committed secret, tell the user it must be rotated. Removing it from the file is not enough.
+
+## 4. Make every change idempotent
+
+1. Declarative first: Ansible resource modules with `state: merged` (add/update only) or `state: replaced` (this resource exactly). Treat `state: overridden` and NAPALM `load_replace_candidate` as high risk: anything not in your data is removed. Confirm with the user before using them.
+2. With `ios_config`/`*_config` line modules, give `parents` and `lines` that match the running config exactly as the device prints it, or every run reports a change.
+3. Netmiko is not idempotent: `send_config_set` sends whatever you give it. Fetch the running config first, compute what is missing, and send only that.
+4. A second run against an unchanged device must report zero changes. Test this in the lab.
+
+## 5. Dry run and diff
+
+- Ansible: `ansible-playbook site.yml --check --diff --limit <canary>`.
+- NAPALM: `load_*_candidate`, print `compare_config()`, then `discard_config()`.
+- Nornir: `napalm_configure(dry_run=True)` or `InitNornir(dry_run=True)`; print `result.diff`.
+- Netmiko: show the computed command list and the current running section side by side.
+
+Show the diff to the user. **Stop and ask** before committing if the diff touches management access (VTY lines, ACLs on the management interface, AAA, SSH, routing toward the management network) or deletes anything.
+
+## 6. Rollback
+
+1. Take a backup of the running config before every push (`ios_config: backup: true`, NAPALM `get_config()`, or `show running-config` saved per host with a timestamp).
+2. Use the platform's confirmed commit so a change that cuts you off reverts on its own:
+   - NAPALM: `commit_config(revert_in=300)` then `confirm_commit()` after checks pass. On IOS this needs the `archive` feature; the driver rounds down to whole minutes and accepts 60 to 7200 seconds (IOS `revert timer` is 1 to 120 minutes).
+   - Junos: `commit confirmed <minutes>` then `commit` to confirm. IOS-XR: `commit confirmed <seconds>` (or `commit confirmed minutes <n>`; the bare number is seconds, and the allowed range differs by release, so check that release's command reference) then `commit`. Cisco IOS by hand: see the `cisco-ios-config` skill.
+3. Rollback plan in the change ticket: the command or playbook that restores the backup, tested in the lab.
+
+## 7. Rollout
+
+1. Lab first, then one canary, then batches: Ansible `serial: [1, 5, "25%"]` with `max_fail_percentage: 0` (the percentage must be exceeded, so any failure in a batch stops the play); Nornir: filter to a small group per run.
+2. Capture state before and after: interfaces up, neighbors (`get_lldp_neighbors`, OSPF/BGP neighbor counts), route counts. Compare; any drop stops the rollout.
+3. Save to startup only after verification (`save_when: modified`, Netmiko `save_config()`).
+4. Stop on the first unexpected failure. Do not retry a failed push in a loop.
+
+## 8. Test
+
+- Lab: containerlab topology (`clab deploy -t lab.clab.yml`) with vendor images the user is licensed for, or CML/GNS3/EVE-NG.
+- Offline: render templates in CI and run `ansible-playbook --syntax-check`, `ansible-lint`, or unit tests on the rendering. Batfish can check reachability and ACL behaviour on rendered configs without devices.
+- State checks: `napalm_validate` with a validation YAML, or pyATS/Genie parsers.
+
+## Never
+
+- Run against `all` hosts without a `--limit` or filter on the first run.
+- Disable SSH host key checking permanently in shared config. Accepting keys in a lab is fine; say so in the file.
+- Push to production without a diff the user has seen, a backup, and a rollback path.
+- Store device output containing secrets in CI logs or artifacts.
+
+## Report back
+
+```
+Targets: <hosts/groups>, platform(s)
+Tool and mode: <tool>, <merge|replace|resource state>
+Dry-run diff: <summary, lines added/removed per host>
+Applied: <yes/no>, rollback mechanism: <revert timer / backup path>
+Verification: <checks run, before/after counts>
+Idempotency: second run changed = <0 or list>
+Open risks: <anything not tested in the lab>
+```

package/skills/network-automation/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Write a Nornir script that pushes our NTP and syslog template to 200 IOS-XE switches with a dry run first",
+    "My Ansible ios_config task reports changed on every run even though nothing is different, why?",
+    "Should we use NAPALM or plain Netmiko to roll out ACL updates across Arista and Cisco boxes?",
+    "Add an automatic revert to our NAPALM deploy so a bad push doesn't strand us without SSH",
+    "Our network inventory YAML has device passwords in plaintext, move them to vault or env vars",
+    "Set up a containerlab topology so we can test our Ansible network playbooks before production"
+  ],
+  "should_not_trigger": [
+    "Our eBGP session to the transit provider keeps flapping between Active and Idle",
+    "Write the IOS commands to make Gi1/0/5 an access port in VLAN 30 with portfast",
+    "Review this OPNsense config.xml for anything exposed on the WAN side",
+    "Traceroute from the app server dies at the second hop, help me find where packets drop",
+    "Write a Terraform module for an Azure virtual network with two subnets",
+    "Write an Ansible playbook that installs nginx and certbot on Ubuntu servers"
+  ]
+}

package/skills/network-automation/references/tool-snippets.md

@@ -0,0 +1,153 @@
+# Tool snippets
+
+Minimal, working shapes. Adapt names to the repo; keep secrets out of every file shown.
+
+## Netmiko
+
+```python
+import os
+from netmiko import ConnectHandler
+
+device = {
+    "device_type": "cisco_ios",          # cisco_xe, cisco_nxos, arista_eos, juniper_junos ...
+    "host": "10.0.0.11",
+    "username": os.environ["NET_USER"],
+    "password": os.environ["NET_PASS"],
+    "secret": os.environ.get("NET_ENABLE", ""),
+}
+with ConnectHandler(**device) as conn:
+    conn.enable()
+    # Read only the interface you change, so a match elsewhere cannot hide a missing line.
+    running = conn.send_command("show running-config interface GigabitEthernet1/0/10")
+    wanted = ["interface GigabitEthernet1/0/10", " description uplink-core1"]
+    # Send only what is missing; Netmiko does not diff for you.
+    if not any(line.strip() == "description uplink-core1" for line in running.splitlines()):
+        print(conn.send_config_set(wanted))
+        conn.save_config()
+```
+
+`send_command(..., use_textfsm=True)` returns parsed data when a TextFSM (ntc-templates) template exists for that command.
+
+## NAPALM
+
+```python
+from napalm import get_network_driver
+
+driver = get_network_driver("ios")       # eos, junos, nxos, nxos_ssh, iosxr ...
+with driver("10.0.0.11", user, password, optional_args={"secret": enable}) as dev:
+    dev.load_merge_candidate(config=rendered)   # or load_replace_candidate(filename=...)
+    diff = dev.compare_config()
+    if not diff:
+        dev.discard_config()
+    elif approved(diff):
+        dev.commit_config(revert_in=300)        # seconds; IOS rounds to minutes, needs archive
+        if checks_pass(dev):
+            dev.confirm_commit()
+        else:
+            dev.rollback()
+    else:
+        dev.discard_config()
+```
+
+IOS driver prerequisites: `ip scp server enable` on the device, `archive` configured with a local path for revert and replace, and a replace file that matches IOS indentation and ends with `end`.
+
+## Nornir (3.x)
+
+`config.yaml`:
+
+```yaml
+inventory:
+  plugin: SimpleInventory
+  options:
+    host_file: inventory/hosts.yaml
+    group_file: inventory/groups.yaml
+    defaults_file: inventory/defaults.yaml
+runner:
+  plugin: threaded
+  options:
+    num_workers: 10
+```
+
+```python
+import os
+from nornir import InitNornir
+from nornir.core.filter import F
+from nornir_napalm.plugins.tasks import napalm_configure
+from nornir_utils.plugins.functions import print_result
+
+nr = InitNornir(config_file="config.yaml")
+nr.inventory.defaults.username = os.environ["NET_USER"]
+nr.inventory.defaults.password = os.environ["NET_PASS"]
+
+def push(task):
+    # napalm_configure does not expand {host} in filename; build the path per host.
+    return task.run(task=napalm_configure, filename=f"out/{task.host.name}.cfg", dry_run=True)
+
+canary = nr.filter(F(site="lab") & F(role="access"))
+result = canary.run(task=push)
+print_result(result)
+```
+
+`napalm_configure` (signature in the nornir_napalm repo) takes `dry_run`, `filename`, `configuration`, `replace`, `commit_message` and `revert_in`. Render per-host files first, or pass `configuration=` from a task that renders the template.
+
+## Ansible
+
+`inventory/group_vars/ios.yml`:
+
+```yaml
+ansible_connection: ansible.netcommon.network_cli
+ansible_network_os: cisco.ios.ios
+ansible_user: "{{ vault_net_user }}"
+ansible_password: "{{ vault_net_pass }}"
+ansible_become: true
+ansible_become_method: enable
+ansible_become_password: "{{ vault_net_enable }}"
+```
+
+Playbook:
+
+```yaml
+- hosts: ios
+  gather_facts: false
+  serial: [1, 5, "25%"]
+  max_fail_percentage: 0
+  tasks:
+    - name: Backup running config
+      cisco.ios.ios_config:
+        backup: true
+        backup_options:
+          dir_path: backups/
+    - name: VLANs as data
+      cisco.ios.ios_vlans:
+        config: "{{ vlans }}"
+        state: merged          # replaced / overridden remove what is not listed
+    - name: Save if running differs from startup
+      cisco.ios.ios_config:
+        save_when: modified
+```
+
+Run: `ansible-playbook site.yml --check --diff --limit lab-sw1`, then without `--check` on the same limit, then widen.
+
+`state: rendered` prints the commands a resource module would send without connecting; `state: gathered` reads current state as structured data, useful for before/after checks.
+
+## containerlab
+
+```yaml
+name: lab
+topology:
+  nodes:
+    sw1: { kind: arista_ceos, image: ceos:<version you have> }
+    sw2: { kind: arista_ceos, image: ceos:<version you have> }
+  links:
+    - endpoints: ["sw1:eth1", "sw2:eth1"]
+```
+
+`clab deploy -t lab.clab.yml`, `clab inspect`, `clab destroy -t lab.clab.yml`. Vendor images (cEOS for `arista_ceos`, `cisco_iol`, `cisco_c8000v` built with vrnetlab) must be obtained under the vendor's licence. Kind names: https://containerlab.dev/manual/kinds/
+
+## Sources
+
+- NAPALM base API (`commit_config(revert_in=seconds)`): https://napalm.readthedocs.io/en/latest/base.html ; IOS caveats (archive, `ip scp server enable`, replace file format): https://napalm.readthedocs.io/en/latest/support/ios.html
+- Ansible `serial` lists: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_strategies.html ; `max_fail_percentage`: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_error_handling.html
+- `cisco.ios.ios_config` (`backup_options`, `save_when`) and `ios_vlans` states: https://github.com/ansible-collections/cisco.ios
+- IOS-XR `commit confirmed`: https://www.cisco.com/c/en/us/td/docs/iosxr/cisco8000/system-management/b-system-management/m-conf-mgmt-commands.html
+- containerlab deploy: https://containerlab.dev/cmd/deploy/