fstubner · fstubner · Oct 2, 2026 · Oct 1, 2026 · Oct 1, 2026 · Oct 1, 2026
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -93,6 +93,18 @@ holds no credentials.
 - Do not add GUI-only, TUI-only, CLI-only, or MCP-only network logic. Interfaces should call `netscli-core` or add a missing operation to `Ops`.
 - Do not weaken safety limits in `ops/` or MCP validation without a separate review.
 
+## Adding A Network Capability
+
+Moved here from the public docs page `core-library.md`, which is for library
+users rather than contributors.
+
+1. Add the behavior and tests in `netscli-core`.
+2. Expose it through `Ops`.
+3. Add CLI handling and structured output.
+4. Add TUI and desktop app presentation if the workflow fits those interfaces.
+5. Add MCP exposure only when an agent use case is clear and safe.
+6. Update the result-model docs when output fields change.
+
 ## Contribution Gates
 
 Run the narrowest relevant checks while iterating, then the full gate before shipping cross-cutting changes:

diff --git a/site/src/content/docs/docs/cli.md b/site/src/content/docs/docs/cli.md
@@ -6,7 +6,7 @@ head:
     content: Command-line network scanner (CLI) | NetsCLI docs
 ---
 
-The CLI is the best interface for repeatable diagnostics, automation, and machine-readable output.
+Use the CLI for repeatable diagnostics, automation, and machine-readable output.
 
 ## Common commands
 
@@ -52,10 +52,7 @@ netscli discover --json | jq '.[].ip'
 
 ### CSV and Markdown
 
-Commands that return a list also take `--csv`, for a spreadsheet or a script
-that wants columns, and `--md`, for a Markdown table to paste into an issue
-or a wiki: `discover`, `scan`, `sweep`, `dns`, `ping`, `arp`, `interfaces`,
-`mdns` and `pcap`.
+Commands that return a list also take `--csv`, for a spreadsheet or a script that wants columns, and `--md`, for a Markdown table to paste into an issue or a wiki. They are `discover`, `scan`, `sweep`, `dns`, `ping`, `arp`, `interfaces`, `mdns` and `pcap`.
 
 ```bash
 netscli discover 192.168.1.0/24 --csv > hosts.csv
@@ -93,8 +90,7 @@ $ netscli dns netscli.com --record MX --md
 
 ## Example output
 
-Captured from a real run against loopback, so every port reads `filtered` —
-nothing is listening on 127.0.0.1 for these ports. A host with services up
+Captured from a real run against loopback, so every port reads `filtered`, because nothing is listening on 127.0.0.1 for these ports. A host with services up
 returns `open` with latency, and a banner where one was offered.
 
 ```console
@@ -121,8 +117,7 @@ $ netscli scan 127.0.0.1 -p 22,80,443 --json
 ]
 ```
 
-`open` is the compatibility boolean older consumers already read; `status`
-carries the four-way answer. Both are present, so a script written against
+`open` is the compatibility boolean older consumers already read, and `status` carries the full answer, including `open|filtered` for UDP. Both are present, so a script written against
 either keeps working.
 
 ```console
@@ -167,7 +162,7 @@ The CLI exposes shared network operations plus command-line maintenance workflow
 | --- | --- |
 | `discover` | Find reachable hosts on a subnet. |
 | `scan` | Scan TCP ports on one host, or UDP services with `--udp`. |
-| `inspect` | Build a host profile from reachability, reverse DNS, and optional ports. |
+| `inspect` | Build a host profile with reachability, reverse DNS, MAC address and maker, an OS hint, and optional ports. |
 | `sweep` | Discover hosts and scan selected ports across them. |
 | `ping` | Measure reachability and packet loss. |
 | `trace` | Show route hops to a host. |
@@ -194,7 +189,7 @@ netscli dns --help
 
 `--concurrency` / `-j` is a global option for limiting in-flight network work. It is useful on fragile gateways or when scanning larger local ranges.
 
-The help output is the source of truth for flags. The docs explain workflow and intent; the binary explains exact syntax.
+The help output is the source of truth for flags. The docs explain workflow and intent, and the binary explains exact syntax.
 
 ## CLI-only workflows
 
@@ -204,10 +199,9 @@ Some workflows intentionally stay in the command-line interface:
 - `serve` and `mcp-service` for MCP server launch and supported service management.
 - Shell completions and manpage generation.
 
-The desktop app exposes shared network operations and result exploration. It does not duplicate maintenance workflows unless they become shared core operations with a clear interactive use case.
 
 ## Permissions and limits
 
 Raw ICMP, traceroute, and packet capture can require elevated permissions depending on the platform. Port scans and DNS lookups normally do not.
 
-The core library enforces safety limits for subnet size, port count, concurrency, and timeouts. Interface-specific code does not bypass those limits.
+Limits on subnet size, port count, concurrency, and timeouts apply the same way in every interface.
diff --git a/site/src/content/docs/docs/core-library.md b/site/src/content/docs/docs/core-library.md
@@ -3,7 +3,7 @@ title: Core library and crates
 description: NetsCLI Rust crate ownership, core library boundaries, and integration rules.
 ---
 
-NetsCLI is split into Rust crates and interface apps. `netscli-core` owns network behavior; the CLI, TUI, desktop app, and MCP server call into it rather than carrying separate implementations.
+NetsCLI is split into Rust crates and interface apps. `netscli-core` owns network behavior, and the CLI, TUI, desktop app, and MCP server call into it rather than carrying separate implementations.
 
 Interface layers use the core `Ops` facade instead of implementing their own probes, packet parsing, DNS behavior, or scan safety logic.
 
@@ -34,17 +34,7 @@ Dependency flow stays one-way:
 Interface crates may depend on the core. The core must not depend on a UI layer, MCP protocol layer, or desktop runtime.
 
 The CLI additionally depends on `netscli-mcp`, because `netscli serve` runs
-the MCP server in-process — the one edge between two interface crates. The
-diagram previously showed all three as siblings, which made `netscli serve`
-look impossible.
-
-## Ownership rules
-
-- Put scan, discovery, ping, DNS, ARP, sweep, inspect, stats, database, and packet capture logic in `netscli-core`.
-- Expose missing operations through `Ops` so CLI, TUI, desktop app, and MCP all benefit.
-- Keep public structures additive when possible.
-- Keep safety limits centralized.
-- Add core tests when behavior changes.
+the MCP server in-process. It is the one dependency between two interface crates.
 
 ## Public facade
 
@@ -56,9 +46,6 @@ Most consumers start from `Ops`.
 | `OpsConfig` | Runtime defaults for scan, ping and DNS timeouts, plus probe concurrency. |
 | Result structs | Shared data returned by scans, discovery, DNS, ARP, interfaces, sweep, inspect, and packet capture. |
 
-Expose new behavior through the facade so every interface gets the
-same capability and the same safety behavior.
-
 Typical integration shape:
 
 ```rust
@@ -82,9 +69,9 @@ Exact method signatures can change as operations gain richer structured data. Pr
 
 | Module | Owns |
 | --- | --- |
-| `scan` | TCP port scanning, status classification, latency, banner, HTTP, and TLS probing. |
+| `scan` | TCP and UDP port scanning, status classification, latency, banner, HTTP and TLS probing, and service versions. |
 | `discover` | Host discovery over a subnet. |
-| `inspect` | Host profile data built from reachability, reverse DNS, and port checks. |
+| `inspect` | Host profile data built from reachability, reverse DNS, MAC address, port checks, and the OS hint. |
 | `sweep` | Discovery plus per-host port checks. |
 | `ping` | Reachability probing, with the ICMP and TCP-connect backends. |
 | `trace` | Route hops, over the platform trace tool. |
@@ -96,36 +83,18 @@ Exact method signatures can change as operations gain richer structured data. Pr
 | `db` | SQLite persistence for host records and scan history. |
 | `ops` | Cross-interface operation orchestration and limits. |
 
-## Interface responsibilities
-
-- CLI: parse arguments and format text, JSON, or YAML.
-- TUI: present terminal state and keyboard interactions.
-- Desktop app: render app state, tables, settings, details, exports, and Tauri command calls.
-- MCP: expose core operations through JSON-RPC tools.
-- Tauri backend: bridge desktop app commands to `netscli-core`.
-
-When adding a new network capability:
-
-1. Add the behavior and tests in `netscli-core`.
-2. Expose it through `Ops`.
-3. Add CLI handling and structured output.
-4. Add TUI and desktop app presentation if the workflow fits those interfaces.
-5. Add MCP exposure only when an agent use case is clear and safe.
-6. Update result-model docs when output fields change.
-
 ## Safety limits
 
 NetsCLI intentionally limits expensive operations:
 
-- Maximum subnet size: `/16`.
-- Maximum ports per scan: `4096`.
-- Default concurrency: `256`.
-- Default scan timeout: `500 ms`.
+- Subnets up to `/16`.
+- Up to `4096` ports per scan.
+- `256` probes in flight by default.
+- A `500 ms` scan timeout by default.
 
-## Compatibility rules
+## Contributing
 
-- Change public result structures additively where possible.
-- Avoid renaming CLI flags without a breaking-release note.
-- Keep MCP tool names and input schemas stable.
-- SQLite schema changes require migration planning.
-- Desktop-app-only network behavior is not allowed; network logic belongs in the core.
+The rules for where new code goes, how a new operation reaches every
+interface, and what has to stay compatible are in
+[ARCHITECTURE.md](https://github.com/fstubner/netscli/blob/main/docs/ARCHITECTURE.md)
+in the repository.
diff --git a/site/src/content/docs/docs/desktop.md b/site/src/content/docs/docs/desktop.md
@@ -51,7 +51,7 @@ Use the CLI instead when you need setup, doctor, shell completions, manpages, se
 
 ## Operation tabs
 
-Tabs show the operation name and a short identifier such as host, subnet, interface, or record name. They do not show the full command; the command preview lives in the command bar.
+Tabs show the operation name and a short identifier such as host, subnet, interface, or record name. They do not show the full command. The command preview lives in the command bar.
 
 Supported operations include:
 
@@ -98,7 +98,7 @@ The details pane changes when multiple rows are selected. Instead of duplicating
 The details pane is operation-specific:
 
 - Scan rows explain open, closed, filtered, and error states.
-- Inspect shows a host overview, checked ports, and raw data.
+- Inspect shows a host overview, the MAC address and maker, an OS hint with its clues, checked ports, and raw data.
 - Discover and Sweep summarize device inventory and exposed services.
 - DNS shows record values and metadata such as TTL or resolver source when available.
 - Interfaces shows state, addresses, MAC, selected/default hints, and loopback or virtual hints.
@@ -137,12 +137,9 @@ Settings control:
 ## Updates
 
 When the app opens, it checks GitHub for a newer release. If there is one, a
-notice appears in the corner. The check fetches one small file and nothing
-else; turn it off under **Settings → Release Notifications**.
+notice appears in the corner. The check fetches one small file and nothing else. You can turn it off under **Settings → Release Notifications**.
 
-Where the app can update itself, the notice opens a dialog with the new
-version's release notes and three choices: **Install and restart**, **Later**
-or **Skip this version**. Nothing downloads until you choose to install. The
+Where the app can update itself, the notice opens a dialog with the new version's release notes and three choices, **Install and restart**, **Later** or **Skip this version**. Nothing downloads until you choose to install. The
 update is checked against NetsCLI's signing key before it is installed. On
 Windows the installer shows a progress bar and may ask for administrator
 permission, then the app reopens.
@@ -156,15 +153,15 @@ These installs update themselves:
 These installs belong to a package manager, so the notice links to the
 release page instead and the package manager does the update:
 
-- Scoop: `scoop update netscli-gui`
-- The AUR package: your AUR helper
-- A `.deb`: install the newer `.deb`
+- Scoop updates with `scoop update netscli-gui`
+- The AUR package updates through your AUR helper
+- A `.deb` updates by installing the newer `.deb`
 
 ## Build and runtime availability
 
 Most desktop tools are available in the standard desktop build. Packet capture is handled explicitly:
 
 - Packet Capture stays in the tool list in every build. Running a capture needs a build that includes packet-capture support, plus Npcap on Windows or libpcap on Linux/macOS. Without those, the tab opens and shows setup guidance instead of running.
 - mDNS Discovery is included in the standard published desktop build.
-- A tool whose feature is genuinely absent from the build is hidden. That applies to mDNS Discovery; Packet Capture is the deliberate exception, because the published installers ship without it and a hidden tab explained nothing.
+- In a custom build without mDNS support, mDNS Discovery is hidden.
 - If a required runtime library is missing, only that feature is unavailable. The rest of the desktop app keeps working and shows setup guidance for the missing dependency.
diff --git a/site/src/content/docs/docs/index.md b/site/src/content/docs/docs/index.md
@@ -3,7 +3,7 @@ title: Overview
 description: NetsCLI documentation for the shared Rust core, CLI, TUI, desktop app, and MCP server.
 ---
 
-NetsCLI is a cross-platform network scanner written in Rust. It is built around one shared core library and several interfaces: a desktop app, terminal UI, command-line interface, and MCP server.
+NetsCLI is a cross-platform network scanner written in Rust. It is built around one shared core library and four interfaces, a desktop app, a terminal UI, a command-line interface, and an MCP server.
 
 The goal is consistency. A port scan, DNS lookup, host inspection, or ARP cache read means the same thing whether you run it from the desktop app, a shell script, the TUI, or an AI agent.
 
@@ -14,8 +14,8 @@ NetsCLI focuses on practical network inspection tasks:
 | Task | Use this when |
 | --- | --- |
 | Discover hosts | You want to find reachable devices on a subnet. |
-| Scan TCP ports | You know a host and want port status, latency, service guesses, and optional banner data. |
-| Inspect a host | You want a host profile combining reachability, reverse DNS, and optional port checks. |
+| Scan ports | You know a host and want TCP or UDP port status, latency, the software and version where a service names itself, and banner data. |
+| Inspect a host | You want a host profile with reachability, reverse DNS, MAC address and maker, an OS hint, and optional port checks. |
 | Sweep a subnet | You want discovery plus exposed services across discovered hosts. |
 | Query names | You need DNS, reverse DNS, or local mDNS service information. |
 | Review local inventory | You need local interfaces or the operating system ARP neighbor cache. |
@@ -25,13 +25,13 @@ NetsCLI is not intended to replace tools such as nmap or Wireshark for advanced
 
 ## Interface model
 
-The core library owns network behavior. Interface layers present the data and workflow that fit their environment instead of reimplementing probes, parsers, or safety limits.
+Every interface runs the same core library, so results and limits are the same whichever you use. Each one presents them in the way that suits it.
 
 | Interface | Best fit |
 | --- | --- |
 | Desktop app | Tabbed workflows, filtering, row details, history, exports, and result review. |
 | Terminal UI | Keyboard-first interactive diagnostics inside a terminal session. |
-| CLI | Repeatable commands, scripts, JSON/YAML output, setup, doctor, and shell workflows. |
+| CLI | Repeatable commands, scripts, JSON, YAML, CSV and Markdown output, setup, doctor, and shell workflows. |
 | MCP server | Structured tools for AI agents that need local network operations. |
 | Rust core | Applications that want the shared operations directly. |
 
@@ -49,10 +49,10 @@ Interfaces may add confirmations or guidance, but they do not bypass the core li
 
 ## Useful starting points
 
-- New to NetsCLI: read [Operations](/docs/operations/) first.
-- Installing on Windows, macOS, or Linux: read [Installation](/docs/install/).
-- Comparing desktop app, TUI, CLI, and MCP coverage: read [Interface coverage](/docs/interface-coverage/).
-- Using the desktop app: read [Desktop app](/docs/desktop/).
-- Automating scans or exporting JSON/YAML: read [CLI](/docs/cli/).
-- Integrating with agents: read [MCP server](/docs/mcp/).
-- Building on the Rust crates: read [Core library and crates](/docs/core-library/).
+- If you are new to NetsCLI, start with [Operations](/docs/operations/).
+- [Installation](/docs/install/) covers Windows, macOS and Linux.
+- [Interface coverage](/docs/interface-coverage/) compares the desktop app, TUI, CLI and MCP server.
+- [Desktop app](/docs/desktop/) is the guide to the desktop app.
+- [CLI](/docs/cli/) covers automating scans and exporting JSON, YAML, CSV or Markdown.
+- [MCP server](/docs/mcp/) covers connecting AI agents.
+- [Core library and crates](/docs/core-library/) is for building on the Rust crates.