Use-case guides, first four (phase 3)

[joshdrake]

Needs validation before it is shown. use-cases/sso-device-factor.mdx is written from the API specification, the Terraform provider, and the howto.smallstep.com Okta article; nobody has walked it against the product. It stays hideFromSidebar: true and says so at the top of the page. The Smallstep-side objects (PUT /sso, POST /sso/clients) are documented as customer-created because the public API and the Terraform provider expose them; the internal runbook still creates them in Retool, so a reviewer should confirm the API path works for an entitled team.

Rendering. The pages use Tabs/Tab, <<placeholder>> tokens, and explicit heading ids, which exist only on the website branch josh/docs-content-package (smallstep.com#1220). They render there; on the current site the tokens show as text and the tabs stack.

Phase 3 of the docs redesign: the first four use-case guides on the nine-step skeleton, each with troubleshooting entries and a skill.

Pages

Page	Kind	Built from
use-cases/wifi.mdx	guide	tutorials/protect-wireless-networks.mdx (guide part); melange use-cases/wifi.md, concepts/setup-playbook.md (vendor and MDM tab set); learn/radsec.mdx; the 2025-01-01 spec; Terraform provider 0.7.0 docs
use-cases/wired.mdx	guide	tutorials/protect-wired-networks.mdx; melange use-cases/wired.md (dot3svc, PKCS#11 caveat, vendor list)
use-cases/web-apps.mdx	guide	tutorials/browser-certificate-setup-guide.mdx; melange use-cases/browser-mtls.md; the spec's /protect/browser; Terraform smallstep_browser
use-cases/sso-device-factor.mdx	guide, hidden	melange use-cases/idp-device-factor.md; Notion "Add Smallstep to Okta as an Identity Provider" (Smallstep How-To, 2026-05-12); Notion "Okta: Creating Device IDP Using Retool" (2026-08-18) and "Configure Entra ID MFA [internal]" (2026-03-25) for the redirect URIs and the trust-roots rule; the spec's /sso and /sso/clients; Terraform smallstep_identity_provider*; the Console's Protect › SSO copy
reference/access-points.mdx	reference	the access-point section of the wireless tutorial (all ten vendors)
reference/radius-webhooks.mdx	reference	the RADIUS authorization webhook section of the wireless tutorial
reference/wlan-profile-xml.mdx	reference	the WLAN XML (wireless tutorial) and LAN XML (wired tutorial)
troubleshooting/README.mdx	troubleshooting index	new
troubleshooting/wifi/* (10)	troubleshooting	the wireless tutorial's ChromeOS verify list, Jamf and Intune alerts, and verify section; platform/troubleshooting-agent.mdx (SCEP failures, cannot access a resource, doctor)
troubleshooting/wired/* (4)	troubleshooting	the wired tutorial (switch state, Event Viewer, MAB, issuer hash); melange use-cases/wired.md (dot3svc)
troubleshooting/web-apps/* (4)	troubleshooting	the browser tutorial (policy merge, registry keys, certificate lists); platform/troubleshooting-agent.mdx (PKCS#11, expired certificates)
troubleshooting/sso-device-factor/* (4)	troubleshooting	the Okta how-to article (feature flag, email SAN, picker); the spec's lifecycleFailureURI
skills/{wifi,wired,web-apps,sso-device-factor}/SKILL.md	skill	the guide itself; each says which steps an agent does through the API and which it hands to a person

Old pages stay in the manifest with hideFromSidebar: true and retitled "(previous guide)".

Redirects (for the cutover table)

Old	New
/docs/tutorials/protect-wireless-networks	/docs/use-cases/wifi
/docs/tutorials/protect-wireless-networks#access-point-configuration-reference	/docs/reference/access-points
/docs/tutorials/protect-wireless-networks#radius-authorization-webhooks	/docs/reference/radius-webhooks
/docs/tutorials/protect-wired-networks	/docs/use-cases/wired
/docs/tutorials/browser-certificate-setup-guide	/docs/use-cases/web-apps

Placeholder tokens

From the catalogue: <<team-slug>>, <<ssid>>, <<radius-secret>>, <<authority-id>>, <<acme-directory>>, <<radius-server-name>> (used for serverHostname).

New, to add to the catalogue: <<api-token>>, <<nas-ip>>, <<radius-server-ip>>, <<radius-server-port>>, <<radius-server-id>>, <<credential-id>>, <<wifi-id>>, <<ethernet-id>>, <<browser-id>>, <<app-url>>, <<okta-domain>>, <<idp-issuer>>, <<idp-client-id>>, <<idp-client-secret>>.

<<radius-servers.us-east>> is not used: today's managed RADIUS returns one serverIP; per-region servers are the dedicated deployment, which the guide describes as provisioned by Smallstep.

Choices made

• entitlement: pro on all four guides. The brief said entitlement: team or the tier the melange use-case file names; Team was removed on 2026-09-13 and the use-case files name no tier, so the paid self-serve tier is used. Change in one place per page if the entitlement fragment decides otherwise.
• Vocabulary. "Smallstep RADIUS" throughout; the multi-tenant service is "the API calls it managed RADIUS" once, the dedicated deployment is described without the "Enterprise RADIUS" label. "WAP/NAS IP address" and "Certificate Manager" appear only as parenthetical Console labels. Vendor menu labels are quoted verbatim, which leaves "WiFi" in the UniFi and Workspace ONE menu paths and in the Intune OMA-URI.
• Wired switch tabs. One "Any switch" tab with the source's vendor-neutral shape; the six vendors named in melange are listed as planned rather than invented (WEB-3570).
• Web apps verifier tabs. One "Your app or proxy" tab; Entra CBA, Cloudflare Access, Auth0, Salesforce, and Okta are named as not yet documented.
• Console versus API. The guides create objects with the API, as the current pages and the Quickstart do, because the new Wi-Fi network and RADIUS forms in the Console are behind the internal-only awesomeWifi flag and the customer-visible form is the older one. The Console is named as the place where every object appears.
• Time estimates (20, 15, 15, 30 minutes) are estimates.
• Windows profile XML moved to its own reference page so both network guides share it.
• Vale. API field names added to accept.txt; Device.* keys and <<tokens>> added to TokenIgnores; two code blocks per network guide are wrapped in {/* vale Google.Spacing = NO */} toggles because vale flags Device.Serial inside fenced code. The toggles render to nothing (checked).

Checks

• vale --no-wrap --glob='!step-cli/reference/**' on all 31 new pages: 0 errors (with mdx2vast installed per CONTRIBUTING).
• markdown-link-check -q -c .github/mdl.config.json per new page: 0 dead links. One false positive removed: the checker cannot resolve {#id} explicit anchors within a page, so the Wi-Fi verify step names step 8 in prose instead of linking #troubleshoot.
• Stop-word grep: clean apart from the parenthetical labels and vendor menu paths above.
• All nine anchors present, in order, in each guide (what-you-get, before-you-start, create, configure-external, deliver, verify, operate, troubleshoot, automate).
• Manifest script: 384 entries, every path exists, no orphan .mdx outside .claude/, step-cli/reference/, skills/, and the two known exceptions.
• Render check on the website branch (next dev -p 5052, content/docs symlinked to this branch): every new page returns 200 with no runtime error; the four guides render two tab lists each (steps 4 and 5); placeholder chips render in prose and in fenced code; #what-you-get and #automate ids are present; /docs/use-cases/wifi.md returns the Markdown with tokens intact.

Left out

• Per-vendor switch instructions and verifier-specific (Entra CBA, Cloudflare, Auth0, Salesforce, Okta) steps: no source material exists; named as planned in the pages.
• The Entra ID tab of the SSO guide carries only the redirect URI and the mechanism; the Entra admin steps were not in any source.
• Google Workspace as an SSO identity provider: named, no steps.
• "Test connectivity" and "Join from this device" device checks, hello-mTLS test page, RADIUS regions, and reply attributes as self-serve: not shipped, not described as available.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NZTV2L582SYSGwfbEQyrQL

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}