@ketecode/loom 0.0.0-stage → 0.2.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/

package/skills/network-design/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: network-design
+description: Produces a vendor-neutral design for an enterprise campus or multi-site network before anything is configured, from requirements and an aggregatable IPv4 and IPv6 addressing plan through OSPF area layout, the BGP edge to ISPs, VLANs, VRFs and segmentation zones, first-hop redundancy and dual uplinks, WAN or SD-WAN topology, and a staged cutover plan with rollback points and validation tests. Use when planning a new office, data centre or branch network, redesigning a flat or outgrown network, merging two company networks, choosing between MPLS, internet VPN and SD-WAN, or writing the migration plan for a network change that must not cause an outage.
+license: MIT
+compatibility: Any Agent Skills host. Produces design documents and plans; no device access needed. Device configuration belongs to the vendor or automation skills.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Network design
+
+Turn requirements into a network design someone can build and migrate to safely. This skill decides what the network should be. Typing the config is for the Cisco IOS or network automation skills, diagnosing faults is for network troubleshooting or BGP diagnostics, and a home lab is for the homelab skill.
+
+## 0. Gather requirements (stop and ask for anything missing)
+
+Write down, per site: users and devices now and in three years, critical applications and where they run (on site, data centre, cloud), required uptime, existing hardware and contracts, ISPs and circuits, compliance zones (card data, OT/industrial, guest), and the team's operational skills. Ask for the existing addressing and any overlapping ranges from partners or acquired companies.
+
+Do not design until you know the growth figure, the uptime target and which systems must be isolated.
+
+## 1. Addressing plan
+
+1. Pick a private IPv4 supernet per organisation from RFC 1918 (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) and give each site one contiguous block so it summarises to a single route (for example `10.<site>.0.0/16`). Avoid `192.168.0.0/24` and `192.168.1.0/24` (home VPN clashes) and anything a partner or cloud VPC already uses.
+2. Inside a site, carve by function in fixed positions so every site looks alike: infrastructure (loopbacks `/32`, point-to-points `/31` per RFC 3021), management, users, voice, wireless, servers, IoT, guest.
+3. Size each subnet for the three-year count plus 30 to 50 percent; prefer `/24` for user VLANs for readability unless hosts exceed it.
+4. IPv6: get a provider-independent or provider-assigned prefix, give each site a `/48` (or `/56` for small sites), each VLAN a `/64`. Map the VLAN ID into the IPv6 subnet ID where it fits so addresses are readable.
+5. Reserve blocks for future sites and for NAT, VPN client pools and cloud.
+6. Record the plan as a table: site, function, VLAN ID, IPv4 prefix, IPv6 prefix, gateway, DHCP scope, zone.
+
+## 2. Routing design
+
+- **Interior:** use OSPF (or IS-IS) with area 0 as the backbone. Put each site or region in its own area attached to area 0, and summarise at the area border routers. Use stub or totally stubby areas for branches with one way out. Keep area 0 small and contiguous.
+- **Static routes** only for stub edges with no alternative path, and always with a tracked next hop or floating backup.
+- **BGP edge:** needs your own public ASN and provider-independent (or ISP-assigned and portable) address space; without them, use each ISP's default route with tracked failover and NAT per ISP, and ask the user before planning an ASN or PI request. With them: eBGP to each ISP. Advertise only your own aggregates (inbound and outbound prefix lists, max-prefix limits), register ROAs for RPKI, use local preference to choose the primary exit and AS-path prepending or provider communities to steer inbound traffic. Take default routes, or full tables only if the routers have the memory and you need the path choice. Use iBGP between edge routers.
+- **Cloud and partners:** BGP over IPsec or the provider's private interconnect; filter what each side may send.
+- Make the failure behaviour explicit: for each link and device, write which path traffic takes when it fails and how long convergence takes (BFD where sub-second matters).
+
+## 3. Layer 2 and segmentation
+
+1. Use a collapsed core (core plus access) for one building, three tiers (core, distribution, access) for campuses. Route at the distribution or core; keep VLANs local to an access block, never stretched across the campus or between sites without a clear need (and then use EVPN/VXLAN, not spanning tree across a WAN).
+2. One VLAN per function per access block. Disable unused ports into a parking VLAN; never carry user traffic on VLAN 1; native VLAN unused.
+3. Spanning tree: rapid PVST+ or MST, root bridge pinned on the distribution pair, BPDU guard on edge ports.
+4. Segment by zone (users, servers, management, guest, IoT, card data, OT) with VRFs or firewall zones. Write the inter-zone policy as a matrix (source zone, destination zone, allowed services) with default deny.
+5. Management network out of band or in its own VRF; only jump hosts reach it.
+6. Port security with 802.1X/NAC where the organisation can operate it; otherwise MAC limits and DHCP snooping with dynamic ARP inspection.
+
+## 4. Redundancy
+
+- Gateways: a first-hop redundancy protocol (VRRP per RFC 5798 is the open standard; HSRP or GLBP on Cisco) or an active-active design such as anycast gateways in EVPN, or multi-chassis link aggregation (vPC, MLAG, StackWise Virtual) with LACP uplinks.
+- Every access switch dual-homed to two distribution switches; every distribution switch to two core switches.
+- Two ISPs with different physical paths into the building, on two edge routers and two firewalls in an HA pair.
+- Power: dual PSUs on separate feeds, UPS for core, edge and wireless controllers.
+- Write down single points of failure that remain and why they are accepted.
+
+## 5. WAN and SD-WAN
+
+| Option | Choose when |
+|---|---|
+| MPLS L3VPN | strict latency or SLA needs, carrier-managed QoS, budget allows |
+| Internet with IPsec (hub and spoke or full mesh) | few sites, cost first, team can run VPNs |
+| SD-WAN | many sites, mixed circuits (broadband, LTE/5G, MPLS), need application-aware path choice and central policy |
+
+For SD-WAN: two transports per important site, central controller design and its failure mode, local internet breakout with security (SSE/firewall), QoS classes for voice and critical apps, and how SD-WAN routes are redistributed into OSPF/BGP without loops (tags, filters). Confirm vendor features and licensing with the vendor; do not assume them.
+
+## 6. Migration plan
+
+Write a staged plan. Every stage has: scope, prerequisites, a maintenance window, exact steps, validation tests, a go/no-go decision, and a rollback that is tested and timed.
+
+1. Stage 0: document the current state (configs backed up, current routing tables and traffic baselines captured).
+2. Build the new core or edge in parallel where possible; connect it with a temporary routed link.
+3. Move one low-risk segment or pilot site first; run it for a defined soak period.
+4. Move remaining segments in batches, critical systems last, never all in one window.
+5. Decommission old paths only after the soak and after removing their routes.
+6. Rollback triggers: name them up front (for example, a critical app unreachable for 5 minutes, routing table size off by more than 10 percent).
+
+Validation per stage: reachability between every zone pair the policy allows (and denial for the ones it blocks), gateway failover by shutting one device, ISP failover, DNS and DHCP from each VLAN, application tests by their owners.
+
+## Never
+
+- Never reuse an address range that overlaps another site, partner or cloud network.
+- Never advertise more than your own aggregates to an ISP or accept routes without filters.
+- Never plan a cutover without a tested rollback and a named person who decides go or no-go.
+- Never stretch Layer 2 between sites to avoid re-addressing without the user accepting the risk.
+
+## Report back
+
+```
+Requirements and assumptions: <list, with what the user still has to confirm>
+Addressing plan: <table>
+Routing: <IGP areas, BGP edge, failure paths>
+Segmentation: <zones, VRFs, policy matrix>
+Redundancy: <per layer; remaining single points of failure>
+WAN: <choice and why>
+Migration: <stages with validation and rollback>
+Risks and open questions: <list>
+```

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Design the network for our new three-floor office and two branches: addressing, VLANs, routing and redundancy",
+    "We acquired a company whose 10.0.0.0/16 overlaps ours, plan how to merge the two networks",
+    "Should our 40 retail sites use MPLS, IPsec over broadband, or SD-WAN? Lay out the trade-offs",
+    "Write a staged migration plan with rollback for moving our flat /16 network to segmented VLANs and VRFs",
+    "Plan the OSPF area layout and the BGP edge to two ISPs for our campus and data centre"
+  ],
+  "should_not_trigger": [
+    "Our BGP session with the ISP keeps flapping between Active and Idle, why?",
+    "Give me the IOS commands to configure a trunk port on a Catalyst 9300",
+    "Write an Ansible playbook to push NTP config to 200 switches",
+    "Set up VLANs for IoT devices on my home lab with a Pi-hole",
+    "Users at the branch can't reach the file server, it times out"
+  ]
+}