Rename to nac-analytics with multi-product CLI (#3)

* Rename to nac-analytics with multi-product CLI and documentation restructure.

Rebrand from nac-nd to nac-analytics with a product-scoped CLI
(nac-analytics nexus-dashboard <verb>, nd alias). Split core and
Nexus Dashboard into nac_analytics/core/ and products/nexus_dashboard/.
Slim README with captured product help; per-verb reference under docs/.
Add capture-help script with CI drift check. Reorganise examples under
examples/nexus_dashboard/.

* Simplify docs to match nac-validate: plain-text help, no capture script.

Replace ANSI help blocks with hand-maintained plain-text --help excerpts
in README and docs/commands. Verb pages keep prose and examples only.
Remove scripts/capture-help.py and the CI drift check.

---------

Co-authored-by: Ed Moore <edmoor@cisco.com>

Author: moore-automation

.env.example

@@ -1,15 +1,17 @@
-# nac-nd credentials (gitignored when copied to `.env`).
+# nac-analytics credentials (gitignored when copied to `.env`).
 #
-# Connection, domain, fabric(s), TLS and timing live in `nac-nd.yaml` — copy
+# `ND_*` variables scope to the Nexus Dashboard product (future products use
+# their own prefixes, e.g. `CC_*`). Connection, domain, fabric(s), TLS and timing
+# also live in `nac-analytics.yaml` under `nexus_dashboard:` — copy
 # `config.example.yaml` to get started.
 #
-# Precedence: CLI flags → environment variables → nac-nd.yaml → `.env` in cwd
+# Precedence: CLI flags → environment variables → nac-analytics.yaml → `.env` in cwd
 
 # Required
 ND_USER=admin
 ND_PASSWORD=change-me
 
-# Optional overrides (uncomment to use instead of nac-nd.yaml values)
+# Optional overrides (uncomment to use instead of nac-analytics.yaml values)
 # ND_HOST=nd.example.com
 # ND_DOMAIN=DefaultAuth
 # ND_FABRIC=FABRIC-A
@@ -18,4 +20,4 @@ ND_PASSWORD=change-me
 # ND_JOB_TIMEOUT_MINUTES=60
 # ND_POLL_INTERVAL=15
 # ND_DELTA_DETAIL=resources
-# ND_CONFIG=/path/to/nac-nd.yaml
+# ND_CONFIG=/path/to/nac-analytics.yaml

.github/workflows/test.yml

@@ -35,7 +35,7 @@ jobs:
       # [tool.bandit]. The toml extra supplies the pyproject config reader.
       - name: Run bandit security scan
         run: >
-          uvx --from "bandit[toml]" bandit -c pyproject.toml -r nac_nd/ -ll
+          uvx --from "bandit[toml]" bandit -c pyproject.toml -r nac_analytics/ -ll
           -f json -o bandit-security-report.json
 
       - name: Upload security report
@@ -68,7 +68,7 @@ jobs:
         run: uv run ruff format --check --diff .
 
       - name: Mypy
-        run: uv run mypy nac_nd
+        run: uv run mypy nac_analytics
 
   test:
     name: Tests

.gitignore

@@ -28,6 +28,7 @@ junit.xml
 .env
 .env.*
 !.env.example
+nac-analytics.yaml
 nac-nd.yaml
 
 # Local analysis artefacts (may contain TF variables / credentials)

README.md

@@ -1,190 +1,97 @@
-# nac-nd
+# nac-analytics
 
 > **In development** — install from source today; PyPI release planned.
+> Formerly **nac-nd**. Today it covers Cisco ACI via Nexus Dashboard 4.2.1+; the intent is to grow beyond Nexus Dashboard and add support for additional Cisco products, so one tool can drive change analytics across platforms.
 
-CLI for change analysis on Cisco ACI fabrics via Nexus Dashboard 4.2.1+. Upload a candidate configuration, compare snapshots, or check compliance.
+CLI for change analysis on Cisco ACI fabrics via Nexus Dashboard 4.2.1+.
 
-**Requirements:** Nexus Dashboard 4.2.1+, Python 3.10+, an ACI fabric registered in Nexus Dashboard.
+Commands are grouped per Cisco product: `nac-analytics <product> <command>`.
+Today the product is `nexus-dashboard` (alias `nd`); more products are planned.
+
+## Installation
 
-## Install (from source)
+**Requirements:** Nexus Dashboard 4.2.1+, Python 3.10+, an ACI fabric registered in Nexus Dashboard.
 
 ```bash
-git clone https://github.com/netascode/nac-nd.git
-cd nac-nd
+git clone https://github.com/netascode/nac-analytics.git
+cd nac-analytics
 uv sync --group dev
-uv run nac-nd --help
+uv run nac-analytics --help
 ```
 
-PyPI install (`pip install nac-nd` / `uv tool install nac-nd`) will be added when the first release is published.
-
 ## Quick start
 
 ```bash
-cp config.example.yaml nac-nd.yaml   # edit host, fabric, domain
-cp .env.example .env                 # set ND_USER and ND_PASSWORD (gitignored)
-uv run nac-nd doctor
+cp config.example.yaml nac-analytics.yaml   # edit host, fabric, domain
+cp .env.example .env                 # set ND_USER and ND_PASSWORD
+uv run nac-analytics nd doctor
 ```
 
-Run `nac-nd <command> --help` for all options.
-
-## Configuration
-
-Settings resolve in order: **CLI flags → environment variables → YAML → `.env` in cwd**.
-
-| YAML key | Environment variable | Notes |
-| --- | --- | --- |
-| `host` | `ND_HOST` | Nexus Dashboard hostname (optional `http://` prefix) |
-| `username` / `user` | `ND_USER` | |
-| `password` | `ND_PASSWORD` | Keep in env/CI secrets, not YAML |
-| `domain` | `ND_DOMAIN` | Default `DefaultAuth` |
-| `fabric` | `ND_FABRIC` | Default fabric for commands |
-| `fabrics` | — | List for `compliance --all` |
-| `verify_ssl` / `verify_tls` | `ND_VERIFY_SSL` | `ND_VERIFY_TLS` accepted as alias |
-| `ca_bundle` | `ND_CA_BUNDLE` | |
-| `job_timeout_minutes` | `ND_JOB_TIMEOUT_MINUTES` | |
-| `poll_interval` | `ND_POLL_INTERVAL` | |
-| `delta_detail` | `ND_DELTA_DETAIL` | Overrides `--detail` default |
-
-Config file locations: `--config path`, `ND_CONFIG`, `./nac-nd.yaml`, or `~/.config/nac-nd/config.yaml`.
-
-## Commands
-
-All primary inputs use **positional arguments** (not flags):
+## Exit codes
 
-| Command | Syntax |
+| Code | Meaning |
 | --- | --- |
-| `prechange` | `nac-nd prechange <plan.json> [<baseline>]` or `nac-nd prechange --job-id <id>` |
-| `snapshots` | `nac-nd snapshots <selector>` |
-| `delta` | `nac-nd delta [<pre>] [<post>]` |
-
-`prechange` and `delta` are **gate commands**: they fail on new `critical`/`major` anomalies by default, write JUnit to `prechange-report.xml` / `delta-report.xml`, and print a one-line verdict on stderr. Use `--output text` for a full human-readable report.
-
-### doctor — check connectivity
-
-```bash
-nac-nd doctor
-```
-
-### prechange — Terraform plan (Network as Code)
-
-Use with [Network as Code](https://netascode.cisco.com) projects: run `terraform plan`, export JSON, analyse before apply.
-
-```bash
-terraform plan -out=plan.tfplan
-terraform show -json plan.tfplan > plan.json
-nac-nd prechange plan.json
-```
-
-- **Exit 0** — DECISION: PASS  
-- **Exit 3** — DECISION: FAIL  
-- Writes `prechange-report.xml` automatically  
-- Use `--fail-on none` to report only (always exit 0)  
-- Use `--output text` for the full change-approval report on stdout
-
-Optional baseline positional (defaults to `latest`):
-
-```bash
-nac-nd prechange plan.json latest-1
-```
-
-Resume or fetch an existing analysis (no re-upload) — useful after a timeout while ND was still queued:
-
-```bash
-nac-nd prechange --job-id <job-id> --fail-on none
-```
-
-`--job-id` waits if the job is still running, then writes the report from the completed result.
-
-### prechange — APIC MO JSON
-
-```bash
-nac-nd prechange examples/minimal-change.json --output text
-```
-
-### snapshots — pin a snapshot ID
-
-```bash
-SNAPSHOT_ID=$(nac-nd snapshots latest)
-```
-
-Text output is the snapshot ID only (for `$()` capture). Use `--output json` for the full record.
-
-### delta — compare snapshots
-
-```bash
-nac-nd delta                    # latest-1 vs latest (ad-hoc only)
-nac-nd delta abc-123            # pinned pre, post defaults to latest
-nac-nd delta abc-123 def-456    # both pinned
-```
-
-Writes `delta-report.xml` by default. Selectors: `latest`, `latest-N`, or a snapshot ID.
-
-### compliance — rule status
-
-```bash
-nac-nd compliance
-nac-nd --config nac-nd.yaml compliance --all --fail-on-violations
-```
-
-## CI/CD
-
-Gate commands need **no extra flags** in CI — fail on exit code, not by parsing output:
-
-```yaml
-- name: Pre-change analysis
-  run: nac-nd prechange plan.json
-
-- name: Pin baseline snapshot
-  id: baseline
-  run: echo "snapshot_id=$(nac-nd snapshots latest)" >> "$GITHUB_OUTPUT"
+| 0 | Success; threshold not breached |
+| 1 | Unexpected error |
+| 2 | Analysis job failed, stopped, vanished, or timed out |
+| 3 | New anomalies at `--fail-on` (or compliance violations with `--fail-on-violations`) |
+| 4 | Bad input, config, or configuration rejected by Nexus Dashboard |
+| 5 | Authentication or authorisation failure |
 
-- run: terraform apply -auto-approve plan.tfplan
+## Nexus Dashboard commands
 
-- name: Post-apply delta
-  run: nac-nd delta "${{ steps.baseline.outputs.snapshot_id }}"
 ```
-
-Pin the baseline snapshot ID saved **before** apply. Do not rely on `nac-nd delta` with no arguments in CI — another snapshot may arrive between stages.
-
-Optional: upload auto-generated reports:
-
-```yaml
-- uses: actions/upload-artifact@v4
-  if: always()
-  with:
-    name: nd-reports
-    path: |
-      prechange-report.xml
-      delta-report.xml
+$ nac-analytics nexus-dashboard --help
+
+Usage: nac-analytics nexus-dashboard [OPTIONS] COMMAND [ARGS]...
+
+Change analysis for Cisco Nexus Dashboard 4.2.1+ (GA REST APIs, ACI).
+
+Configuration:
+ ND_HOST                 Nexus Dashboard hostname or IP
+ ND_USER                 Login username
+ ND_PASSWORD             Login password
+ ND_DOMAIN               Login domain
+ ND_FABRIC               Default ACI fabric name
+ ND_VERIFY_SSL           Verify TLS certificate (ND_VERIFY_TLS accepted)
+ ND_CA_BUNDLE            Path to CA bundle
+ ND_JOB_TIMEOUT_MINUTES  Minutes to wait for analysis jobs
+ ND_POLL_INTERVAL        Seconds between job status polls
+ ND_DELTA_DETAIL         Default --detail for prechange and delta
+ ND_CONFIG               Path to YAML config file
+
+In YAML, nest these under a `nexus_dashboard:` section. Settings load from
+CLI flags, then environment variables, nac-analytics.yaml, or .env.
+
+Options:
+  --help          Show this message and exit.
+
+Commands:
+  prechange   Analyse a candidate configuration against a fabric's current state.
+  delta       Compare two snapshots of a fabric and report what changed.
+  snapshots   Resolve a fabric snapshot and print its ID (for CI baseline pinning).
+  compliance  Report compliance rule status for a fabric (or every fabric with --all).
+  doctor      Check connectivity, credentials, and fabric visibility.
 ```
 
-### Local full pipeline
+Verb-level usage and examples: [command reference](docs/commands/README.md).
 
-After exporting a Terraform plan from `examples/terraform`:
+## Configuration
 
-```bash
-PLAN_FILE=examples/terraform/plan.json ./examples/ci-pipeline.sh
-```
+Precedence: CLI flags → environment variables → YAML → `.env` in cwd.
 
-See [examples/README.md](examples/README.md) for APIC credentials and apply steps.
+Settings are scoped per product. See [config.example.yaml](config.example.yaml) and [Configuration](docs/configuration.md) for the full variable list and YAML layout.
 
-## Exit codes
+## Documentation
 
-| Code | Meaning |
+| Topic | Link |
 | --- | --- |
-| 0 | Success; threshold not breached |
-| 1 | Unexpected error |
-| 2 | Analysis job failed, stopped, vanished, or timed out |
-| 3 | New anomalies at `--fail-on` (or compliance violations with `--fail-on-violations`) |
-| 4 | Bad input, config, or configuration rejected by Nexus Dashboard |
-| 5 | Authentication or authorisation failure |
+| Documentation hub | [docs/README.md](docs/README.md) |
+| Command reference (global + verbs) | [docs/commands/README.md](docs/commands/README.md) |
+| Configuration | [docs/configuration.md](docs/configuration.md) |
+| Development | [docs/development.md](docs/development.md) |
+| Examples & CI pipeline | [examples/README.md](examples/README.md) |
 
 ## Development
 
-```bash
-uv sync --group dev
-uv run pytest
-uv run ruff check .
-uv run ruff format --check .
-uv run python -m mypy nac_nd
-```
+Contributors: see [Development](docs/development.md).

config.example.yaml

@@ -1,34 +1,44 @@
-# nac-nd YAML configuration (safe to commit).
+# nac-analytics YAML configuration (safe to commit).
 #
-# Copy to `nac-nd.yaml` or `~/.config/nac-nd/config.yaml`, or pass
+# Copy to `nac-analytics.yaml` or `~/.config/nac-analytics/config.yaml`, or pass
 # `--config /path/to/this/file`.
 #
+# Settings are scoped per Cisco product. Nest a product's settings under its
+# section (`nexus_dashboard:` today; more products later). Each product reads
+# only its own section.
+#
 # Keep secrets out of this file — use `.env` or the environment for
 # ND_USER and ND_PASSWORD (see `.env.example`).
+#
+# ---------------------------------------------------------------------------
+# Supported variables — nexus_dashboard section
+# ---------------------------------------------------------------------------
+#   Key                  Env var                 Description
+#   host                 ND_HOST                 Hostname or IP (HTTPS assumed when no scheme given).
+#   domain               ND_DOMAIN               Login domain (DefaultAuth, local, or your LDAP domain).
+#   verify_ssl           ND_VERIFY_SSL           Verify TLS cert (ND_VERIFY_TLS also accepted).
+#   ca_bundle            ND_CA_BUNDLE            Path to a CA bundle for private/self-signed certs.
+#   fabric               ND_FABRIC               Default fabric when a command needs one and --fabric is omitted.
+#   fabrics              —                       Fabrics `compliance --all` checks (defaults to [fabric]).
+#   job_timeout_minutes  ND_JOB_TIMEOUT_MINUTES  Minutes to wait for a pre-change analysis job.
+#   poll_interval        ND_POLL_INTERVAL        Seconds between job status polls.
+#   delta_detail         ND_DELTA_DETAIL         Default detail: none, resources, anomalies, policy-diff, full
+#                                                (prechange defaults to `full`; delta to `resources`).
+#
+#   Credentials (secrets — set via environment, not here):
+#   username             ND_USER                 Login username.
+#   password             ND_PASSWORD             Login password.
+# ---------------------------------------------------------------------------
 
-# Nexus Dashboard hostname or IP (HTTPS is assumed when no scheme is given).
-host: nd.example.com
-
-# Login domain (DefaultAuth, local, or your LDAP domain name).
-domain: DefaultAuth
-
-# TLS verification. Set false only on trusted lab clusters with self-signed certs.
-verify_ssl: true
-# ca_bundle: /path/to/nd-cluster-ca.pem
-
-# Default fabric when a command needs one and --fabric is omitted.
-fabric: FABRIC-A
-
-# Every fabric `compliance --all` checks (defaults to [fabric] when omitted).
-fabrics:
-  - FABRIC-A
-  - FABRIC-B
-
-# Pre-change analysis can sit in ND's queue before running; raise on slow clusters.
-job_timeout_minutes: 30
-poll_interval: 15
-
-# Default for `delta --detail` and YAML override for both gate commands.
-# prechange defaults to `full` when unset; delta defaults to `resources`.
-# Values: none, resources, anomalies, policy-diff, full
-delta_detail: resources
+nexus_dashboard:
+  host: nd.example.com
+  domain: DefaultAuth
+  verify_ssl: true
+  # ca_bundle: /path/to/nd-cluster-ca.pem
+  fabric: FABRIC-A
+  fabrics:
+    - FABRIC-A
+    - FABRIC-B
+  job_timeout_minutes: 30
+  poll_interval: 15
+  delta_detail: resources