docs: improve layout phase 1

docs/contributing/index.md

@@ -0,0 +1,78 @@
+# Contributing
+
+This section is for people changing UnderStack itself, rather than deploying or
+operating it.
+
+!!! note "This front door is new and incomplete"
+    Most contributor documentation still lives in `README.md` and
+    `DEVELOPMENT.md` files next to the code. This page links to the main entry
+    points until that material is consolidated here.
+
+## Start here
+
+- [RELEASING.md](https://github.com/rackerlabs/understack/blob/main/RELEASING.md)
+  — how release notes and tags work. Read this before opening a pull request
+  that changes anything an operator has to react to: such a pull request needs a
+  `changelog.d/` fragment, and CI enforces it.
+- [Adding and Removing an Application](../design-guide/add-remove-app.md) — how a
+  component becomes an ArgoCD `Application`.
+- [Design and Background](../openstack-helm.md) — why the project is shaped the
+  way it is, starting with why we diverge from upstream OpenStack Helm.
+
+## Development environments
+
+Each language and package keeps its own setup instructions with the code. These
+links open the current version on GitHub:
+
+| Area | Entry points |
+| --- | --- |
+| Python packages | [Ironic][py-ironic], [Neutron][py-neutron], [Nova][py-nova], [workflows][py-workflows], [OpenStack sync][py-sync] |
+| Go operators and CLIs | [understackctl][go-understackctl], [dexop][go-dexop], [nautobotop][go-nautobotop], [Ironic hardware exporter][go-ihe] |
+| Helm charts | [ArgoCD UnderStack chart][chart-argocd], [site workflows][chart-workflows] |
+| Ansible | [Playbooks and roles][ansible] |
+| Containers | [Ironic][container-ironic], [Nautobot][container-nautobot], [Neutron][container-neutron], [Nova][container-nova] |
+| End-to-end tests | [understack-tests][tests] |
+
+Python packages use [uv](https://docs.astral.sh/uv/) with `pytest` and `ruff`;
+Go projects use a `Makefile` with `golangci-lint`. Run the checks for the area
+you touched before opening a pull request.
+
+## Documentation
+
+The site is built with [properdocs](https://github.com/rackerlabs/properdocs)
+from `properdocs.yml`:
+
+```bash
+make docs-local   # build and serve on http://127.0.0.1:8001
+make docs         # build with --strict, as CI does
+```
+
+Two things to know before you add a page:
+
+- **Every page under `docs/` must appear in `nav:`.** `validation.omitted_files`
+  plus `--strict` makes an unlisted page a build failure. There is no way to ship
+  a page that is not in the navigation, which is deliberate — it is what keeps
+  orphans out.
+- **Some pages are generated**, and are gitignored rather than committed:
+  `docs/workflows/` (from the Argo templates), the neutron sample config, and
+  `docs/release-notes/unreleased.md` (from `changelog.d/`). Use `make docs`
+  rather than calling `properdocs build` directly, or the generated pages will be
+  missing and `--strict` will fail.
+
+[py-ironic]: https://github.com/rackerlabs/understack/blob/main/python/ironic-understack/README.md
+[py-neutron]: https://github.com/rackerlabs/understack/blob/main/python/neutron-understack/DEVELOPMENT.md
+[py-nova]: https://github.com/rackerlabs/understack/blob/main/python/nova-understack/README.md
+[py-workflows]: https://github.com/rackerlabs/understack/blob/main/python/understack-workflows/README.md
+[py-sync]: https://github.com/rackerlabs/understack/blob/main/python/openstack-sync/README.md
+[go-understackctl]: https://github.com/rackerlabs/understack/blob/main/go/understackctl/README.md
+[go-dexop]: https://github.com/rackerlabs/understack/blob/main/go/dexop/README.md
+[go-nautobotop]: https://github.com/rackerlabs/understack/blob/main/go/nautobotop/README.md
+[go-ihe]: https://github.com/rackerlabs/understack/blob/main/go/ironic-hardware-exporter/README.md
+[chart-argocd]: https://github.com/rackerlabs/understack/blob/main/charts/argocd-understack/README.md
+[chart-workflows]: https://github.com/rackerlabs/understack/blob/main/charts/site-workflows/README.md
+[ansible]: https://github.com/rackerlabs/understack/blob/main/ansible/README.md
+[container-ironic]: https://github.com/rackerlabs/understack/blob/main/containers/ironic/README.md
+[container-nautobot]: https://github.com/rackerlabs/understack/blob/main/containers/nautobot/README.md
+[container-neutron]: https://github.com/rackerlabs/understack/blob/main/containers/neutron/README.md
+[container-nova]: https://github.com/rackerlabs/understack/blob/main/containers/nova/README.md
+[tests]: https://github.com/rackerlabs/understack/blob/main/python/understack-tests/README.md

docs/index.md

@@ -32,12 +32,76 @@ hide:
     - OVN networking
     - Prometheus monitoring and metrics stack
 
--   :material-abacus:{ .lg .middle } __Getting Started__
+-   :material-map-marker-path:{ .lg .middle } __How this site is arranged__
 
-    The documentation covers both Kubernetes cluster deployment options and configuration
-    of the UnderStack components for bare metal resource management in a multi-data center
-    environment.
+    Six starting points for five audiences, plus
+    [__Reference__](reference/index.md) for lookup. Pick the card below that
+    describes what you are doing today — most people need one section and can
+    ignore the rest.
 
-    See our [Deploy Guide](deploy-guide/welcome.md) to begin your own deployment.
+    Longer background on the project's goals is in [Vision](vision.md).
+</div>
+<!-- markdownlint-restore -->
+
+## Where do I start?
+
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable MD030 MD032 MD033 MD046 -->
+<div class="grid cards" markdown>
+-   :material-server-network:{ .lg .middle } __I am standing up a cloud__
+
+    ---
+
+    System operator, day 0. A linear install narrative from requirements through
+    to a running site cluster.
+
+    [:octicons-arrow-right-24: Deploy](deploy-guide/welcome.md)
+
+-   :material-lifebuoy:{ .lg .middle } __I am running a cloud__
+
+    ---
+
+    System operator, day 2. Runbooks per service, and a troubleshooting index to
+    land on when something is broken.
+
+    [:octicons-arrow-right-24: Operations](operator-guide/index.md)
+
+    [:octicons-arrow-right-24: Troubleshooting](operator-guide/troubleshooting.md)
+
+-   :material-screwdriver:{ .lg .middle } __I am working on a machine__
+
+    ---
+
+    Data centre technician. Enrolling hardware, device types, firmware and BMC
+    access for an individual server.
+
+    [:octicons-arrow-right-24: Hardware](operator-guide/hardware.md)
+
+-   :material-lan:{ .lg .middle } __I am working on the network__
+
+    ---
+
+    Network operations. Neutron, OVN and Open vSwitch as they are deployed here,
+    and the tenant networking model behind them.
+
+    [:octicons-arrow-right-24: Networking](operator-guide/networking.md)
+
+-   :material-console:{ .lg .middle } __I am using the cloud__
+
+    ---
+
+    Cloud tenant. Driving the OpenStack CLI and APIs to get bare metal servers,
+    images and networks.
+
+    [:octicons-arrow-right-24: Using the Cloud](user-guide/index.md)
+
+-   :material-source-branch:{ .lg .middle } __I am changing UnderStack__
+
+    ---
+
+    Contributor. Development environments, how a component becomes an ArgoCD
+    `Application`, and how release notes work.
+
+    [:octicons-arrow-right-24: Contributing](contributing/index.md)
 </div>
 <!-- markdownlint-restore -->

docs/operator-guide/hardware.md

@@ -0,0 +1,26 @@
+# Hardware Operations
+
+This section is for data centre technicians and operators working with an
+individual physical machine. Start with the task you need to perform:
+
+- [Device Type Management](device-types.md) — define and validate the hardware
+  models supported by a deployment.
+- [Flavor Management](flavors.md) — map resource classes and hardware traits to
+  Nova flavors.
+- [Ironic](openstack-ironic.md) — inspect or manually create bare metal nodes
+  and ports.
+- [Ironic Inspection Guide](openstack-ironic-inspection-guide.md) — diagnose
+  hardware inspection failures.
+- [Change Boot Interface](openstack-ironic-change-boot-interface.md) — change
+  how a node boots for provisioning.
+- [Baremetal Box Cleanup Runbook](baremetal-ironic-cleanup-runbook.md) — recover
+  a node stuck in a failed provisioning state.
+- [Ironic Console](openstack-ironic-console.md) — access a node's serial
+  console.
+- [Server Firmware Updates](server-firmware-update.md) — update firmware from
+  the operator side.
+- [BMC Password](bmc-password.md) — retrieve the generated password for a
+  server's management controller.
+
+Schema definitions for device types, traits, and flavors live under
+[Reference](../reference/index.md#hardware-definitions).

docs/operator-guide/index.md

@@ -1,6 +1,18 @@
-# Operator Guide
+# Operations
 
-This section aims to help users who have to support a running Understack.
+This section is for people supporting a running UnderStack. It covers three
+roles, and the navigation is grouped by which one you are in today:
+
+- **System operators** supporting the deployment as a whole — *Troubleshooting
+  and Architecture*, *OpenStack Services*, *Platform Services*, *Scripts and
+  Tools*.
+- **Data centre technicians** working on an individual machine —
+  [Hardware](hardware.md).
+- **Network operations** working on network configuration —
+  [Networking](networking.md).
+
+If something is broken right now, start at
+[Troubleshooting](troubleshooting.md).
 
 ## Authenticating
 
@@ -39,8 +51,13 @@ be the regular project area.
   deployment between versions. If you deploy from `main`, read the
   [Unreleased](../release-notes/unreleased.md) page.
 
-## Infrastructure Topics
+## Platform Services
+
+The services UnderStack runs alongside OpenStack. Full list in the navigation;
+these are the ones people look for first:
 
+- [ArgoCD Application Management](argocd-helm-chart.md) - Enabling components and
+  pinning versions per cluster
 - [Gateway API Migration Guide](gateway-api.md) - Migration from ingress-nginx to Kubernetes Gateway API with Envoy Gateway
 - [Argo Workflows](workflows.md) - Workflow orchestration and troubleshooting
 - [OpenStack to Nautobot Sync](openstack-nautobot-sync.md) - Event-driven sync and bulk resync operations

docs/operator-guide/networking.md

@@ -0,0 +1,16 @@
+# Network Operations
+
+This section is for network operations and system operators working with
+UnderStack's control plane or tenant data plane:
+
+- [Neutron](openstack-neutron.md) — configure router flavors, service profiles,
+  and VNI allocation.
+- [OVN / Open vSwitch](ovs-ovn.md) — diagnose agents, chassis, logical routers,
+  and traffic flow.
+- [kubectl-us-net](kubectl-us-net.md) — inspect OpenStack and OVN objects through
+  a single troubleshooting CLI.
+- [Neutron Networking Design](../design-guide/neutron-networking.md) — understand
+  the tenant networking and fabric model behind the operational procedures.
+
+For failures that may not be network-specific, start from the broader
+[Troubleshooting index](troubleshooting.md).

docs/operator-guide/troubleshooting.md

@@ -0,0 +1,60 @@
+# Troubleshooting
+
+Somewhere to land from a pager. Troubleshooting material is spread across this
+site by subsystem; this page is the index into it.
+
+!!! tip "If you deploy from `main`"
+    Before anything else, check the
+    [Unreleased release notes](../release-notes/unreleased.md). A deployment
+    tracking `HEAD` picks up changes continuously, and a change that needed
+    operator action is the most likely explanation for something that worked
+    yesterday.
+
+## Start from the symptom
+
+| Symptom | Go to |
+| --- | --- |
+| ArgoCD `Application` stuck syncing, or a sync hook job looping | [Deployment Troubleshooting](../deploy-guide/troubleshooting.md) |
+| An OpenStack service will not start, or a chart will not render | [Troubleshooting OpenStack Helm](troubleshooting-osh.md) |
+| `NeutronAgentDown`, or tenant traffic not passing | [OVN / Open vSwitch](ovs-ovn.md) |
+| A router port is bound to the wrong chassis | [OVN / Open vSwitch](ovs-ovn.md#verifying-a-router-port-is-bound-to-an-ha_chassis_group) |
+| A baremetal node is stuck in `clean wait`, `deleting` or `error` | [Baremetal Box Cleanup Runbook](baremetal-ironic-cleanup-runbook.md) |
+| Inspection is failing or returning nothing | [Ironic Inspection Guide](openstack-ironic-inspection-guide.md) |
+| A node will not PXE boot, or boots the wrong way | [Change Boot Interface](openstack-ironic-change-boot-interface.md) |
+| A workflow failed, or a sensor is not firing | [Argo Workflows](workflows.md#troubleshooting) |
+| Nautobot and OpenStack disagree about a resource | [OpenStack to Nautobot Sync](openstack-nautobot-sync.md) |
+| You need to back up or restore an OpenStack MariaDB database | [MariaDB Operator](mariadb-operator.md) |
+| You need to inspect or back up the Nautobot PostgreSQL database | [Postgres Operator](postgres-operator.md) |
+| A service cannot reach RabbitMQ | [RabbitMQ](rabbitmq.md) |
+| You need access to the Ceph dashboard | [Rook Ceph](rook-ceph.md) |
+| A URL 404s, or TLS is wrong on an endpoint | [Gateway API](gateway-api.md) |
+| An mTLS client is being rejected by Nautobot | [Nautobot mTLS Certificate Renewal](nautobot-mtls-certificate-renewal.md) |
+| You need the generated password for a server's BMC | [BMC Password](bmc-password.md) |
+
+## Working out what happened
+
+- [OpenStack Logging](logging.md) — how to read an OpenStack log line, which is
+  the difference between a request id you can trace and a wall of text.
+- [Monitoring Stack](monitoring.md) — reaching Prometheus and AlertManager, and
+  what the shipped alerts mean.
+- [kubectl-us-net](kubectl-us-net.md) — inspecting UnderStack networking objects
+  from `kubectl` rather than through the OpenStack API, which is what you want
+  when the API itself is the thing that is broken.
+
+## Before you escalate
+
+Have these ready, because they are the first things you will be asked for:
+
+1. The cluster, and whether it is a global or site cluster.
+2. The deployed revision — the `understack_ref` in your deploy repository, and
+   the commit ArgoCD actually has synced. These are not always the same.
+3. The failing resource's identifier: node UUID, port id, `Application` name, or
+   workflow name.
+4. Whether it ever worked, and what changed if so.
+
+## Something missing here?
+
+This page is only as good as its coverage. If you worked out a failure mode that
+is not listed, add the row — and if the page it should point at does not exist,
+that is worth saying too. See
+[Contributing](../contributing/index.md).

docs/reference/index.md

@@ -0,0 +1,51 @@
+# Reference
+
+Lookup material rather than reading material. Nothing here is a narrative — if
+you are trying to *do* something, start from [Deploy](../deploy-guide/welcome.md)
+or [Operations](../operator-guide/index.md) instead and let it send you here.
+
+## Hardware definitions
+
+The schema that hardware is described with, shared by Nautobot and Ironic:
+
+- [Device Types](../design-guide/device-types.md) — the device type schema.
+- [Hardware Traits](../design-guide/hardware-traits.md) — how traits are derived
+  from hardware.
+- [Flavors](../design-guide/flavors.md) — how flavors match hardware.
+
+These are the *definitions*. For the operator procedures that use them, see
+[Device Types](../operator-guide/device-types.md) and
+[Flavors](../operator-guide/flavors.md) under Operations.
+
+## Components
+
+A **component** is an ArgoCD `Application` generated by
+`charts/argocd-understack`. One page per component, listing its sources, scope
+and values:
+
+- [Component Reference](../deploy-guide/components/index.md) — the index, with
+  every component and whether it deploys to a global or site cluster.
+
+## Configuration samples
+
+- [neutron-understack Sample Configuration](../design-guide/neutron-understack-config-sample.md)
+  — generated from the driver's own option definitions, so it is always current
+  for the checked-out revision.
+
+## Workflow templates
+
+The **Workflow Templates** group in the navigation is generated at build time
+from the Argo `WorkflowTemplate` definitions in `workflows/` and
+`components/global-workflows/` — one page per template, showing its parameters
+and the steps it runs. [Enroll Server](../workflows/enroll-server.md) is the one
+to read first, since server enrolment drives most of the others.
+
+Because those pages are generated, they are not committed. Edit the
+`WorkflowTemplate` YAML and re-run `make wftmpls`; do not edit the pages.
+
+## Elsewhere
+
+- [Release Notes](../release-notes/index.md) — what changed between versions, and
+  what an operator has to do about it.
+- JSON schemas for deploy-repository files are published at `/schema/`, and are
+  referenced directly by `$schema=` URLs in `examples/deploy-repo/`.