Docs redesign phase 2: Start here, Learn, Concepts, and the step-ca boundary page

[joshdrake]

Phase 2 of the docs redesign on the next content branch: the Start here pages, the Learn pillar, the Concepts pages, and the open-source boundary page. Every page carries kind: in its frontmatter, uses the glossary vocabulary (the Console label in parentheses once where it differs), and describes only what is shipped; planned items are named in one sentence each and marked as not available.

Pages

Start here

Page	Built from
start-here/how-smallstep-works.mdx (new)	platform/README.mdx ("How can you use Smallstep?"), platform/core-concepts.mdx (the enrollment sequence), melange concepts/object-model.md and concepts/platform-unification.md; Console tab names from the web repo's top navigation on origin/master (Home, Devices, Users, Audit, Protect, Certificate Manager ▾ with Authorities/Endpoints/Certificates)
start-here/quickstart.mdx (replaces stub)	tutorials/protect-wireless-networks.mdx (credential, Managed RADIUS, Wi-Fi resource, agent-managed clients, verify), platform/enrollment-guide.mdx, platform/smallstep-agent.mdx, melange use-cases/wifi.md
start-here/for-coding-agents.mdx (replaces stub)	github.com/smallstep/docs (public; raw files fetch with HTTP 200), smallstep.com/llms.txt (fetched 2026-09-13; indexes the marketing site), platform/smallstep-api.mdx, the Terraform registry, melange plg/agent-readable-onboarding.md and projects/docs-redesign/README.md ("The agent contract") for the Planned section

Learn

Page	Built from
learn/why-device-identity.mdx	platform/README.mdx ("Why cryptographic attested device identity?"), smallstep.com/llms.txt (ACME DA co-developed with Google)
learn/attestation-explained.mdx	platform/core-concepts.mdx (assurance levels, secure elements, the four proofs, key protection levels, the Apple MDA note, the fallback note, the BYO note); the API's HARDWARE_ATTESTED / HARDWARE_WITH_FALLBACK values from the Wi-Fi guide
learn/scep-versus-attestation.mdx	platform/README.mdx (the SCEP critique, static vs dynamic SCEP, the ADCS note), platform/core-concepts.mdx (provisional identity), melange platform/scep-as-credential.md (only for what SCEP is still for; the recipe it proposes is not described)
learn/pki-in-one-page.mdx	step-ca/certificate-authority-core-concepts.mdx (linked, not copied), certificate-manager/how-it-works.mdx (passive vs active revocation), blog "Everything PKI" (linked)
learn/trust-roots-and-chains.mdx	melange concepts/trust.md, architecture/trust-surface.md (the roots.pem URL, the four-places problem); the Wi-Fi, wired, relay, browser, and SSH host pages for where roots go today; certificate-manager/byo-root.mdx
learn/radsec.mdx	melange use-cases/wifi.md; tutorials/protect-wireless-networks.mdx (Managed RADIUS over UDP with nasIPs; Enterprise RADIUS with RadSec and a dedicated hostname, provisioned by Smallstep); tutorials/protect-wired-networks.mdx; RFC 6614 for the protocol
learn/certificates-for-people-devices-and-workloads.mdx	certificate-manager/oidc.mdx (concept part), ssh/how-it-works.mdx (16 h default, principals, GitHub username), melange concepts/inventory.md (workloads), platform/core-concepts.mdx (the delegated pattern), tutorials/cloud-vm-certificate.mdx
learn/how-smallstep-hosts-step-ca.mdx (replaces stub)	melange projects/docs-redesign/boundary.md (the five-anchor outline, followed exactly: #what-is-shared, #what-the-platform-adds, #what-is-different, #which-page, #running-your-own), step-ca/policies.mdx (policy scope), certificate-manager/how-it-works.mdx (Advanced authority options), certificate-manager/oidc.mdx (step ca provisioner against a hosted authority), tutorials/kubernetes-acme-ca.mdx and tutorials/acme-protocol-acme-clients.mdx (linked authorities exist), melange concepts/trust.md

Concepts

Page	Built from
platform/concepts/README.mdx	index with IndexCards
platform/concepts/inventory.mdx	melange glossary.md, concepts/inventory.md; platform/enrollment-guide.mdx; the 2025-01-01 API (/devices, /platforms, /device-enrollment-policy)
platform/concepts/trust.mdx	melange concepts/trust.md, architecture/trust-surface.md; certificate-manager/core-concepts.mdx and how-it-works.mdx; ssh/how-it-works.mdx (Cloud KMS); the API (/authorities, /certificates)
platform/concepts/credentials.mdx	melange glossary.md, concepts/object-model.md; the Wi-Fi guide's credential step; the 2025-01-01 API (/credentials, endpointManagementMode: agent, mdm, other; the deprecation note for /endpoint-configurations and /accounts)
platform/concepts/verifiers.mdx	melange glossary.md, concepts/object-model.md; the Wi-Fi guide's three RADIUS options; tutorials/configure-enterprise-relay.mdx; the API (/managed-radius, /sso)
platform/concepts/policy.mdx	melange concepts/policy.md (the four kinds and the "Today" column only); step-ca/policies.mdx; ssh/acls.mdx; the Wi-Fi guide (reply attributes); platform/enrollment-guide.mdx
platform/concepts/audit.mdx	melange concepts/audit.md (the shipped rows only); certificate-manager/webhook-events.mdx; ssh/how-it-works.mdx; the web repo's top navigation on origin/master (the Audit tab is role-gated, not flag-gated)

Manifest

Start here lists How Smallstep works (new path), Quickstart, and For coding agents, all visible. Learn lists the eight articles in the order above. Concepts gains the index with the six pages as children. platform/README.mdx and platform/core-concepts.mdx stay in the manifest with hideFromSidebar: true so their URLs keep working until the cutover redirects. Every other entry is unchanged, including the two Certificate Manager pages still listed under the Concepts heading.

Choices made

• Audit is described as a tab. melange concepts/audit.md marks the Audit tab internal (flag audit) as of 2026-09-12, but the web repository's top navigation on origin/master gates it by role (owner, admin, device admin), with no feature flag. The page follows the code. If the tab is still flagged in production, change one sentence on platform/concepts/audit.mdx and start-here/how-smallstep-works.mdx.
• Trust is described by what exists. The Trust tab (zones, relationships) is not on web origin/master; the concept page uses the glossary word Trust for the surface, names the Console label (Authorities and Certificates under Certificate Manager) once, and says the Trust tab is planned in one sentence.
• The Quickstart uses the API, as the Wi-Fi guide does, because every value it needs is in one response and the Console's Wi-Fi form fields are not documented anywhere I could cite. It says the same objects can be created under Protect.
• The boundary page's anchor #which-page comes from the heading "Which page?" (the renderer slugifies headings; explicit ids are a phase 3 item).
• The two Certificate Manager pages under the Concepts heading were left as they are per the brief. They now sit beside a concept page named Trust; retitling or hiding them is a one-line manifest change if wanted.
• Vale vocabulary. Added nasIPs, autojoin, serverHostname (API field names that appear in code blocks) and affordances to .vale/styles/config/vocabularies/Smallstep/accept.txt so the new pages lint with zero errors.
• Word counts. attestation-explained (about 1,000 words including its table) and how-smallstep-works (about 940) run slightly over the brief's ranges; the rest are within range.

Checks

• vale --no-wrap --glob='!step-cli/reference/**' on all 18 changed pages: 0 errors, 82 warnings (all Google.Colons on frontmatter, Google.Headings on acronyms, and Oxford-comma suggestions on appositives; the same classes as the next baseline).
• markdown-link-check -q -c .github/mdl.config.json on all 18 pages: 0 dead links (217 links checked).
• Vocabulary grep for the glossary's stop words: only parenthetical Console labels (Certificate Manager, Endpoints, SSH Pro, once per page), API paths, and the boundary page's use of "provisioner" as the step-ca object.
• Manifest script: 355 entries, every path exists, no duplicates; the only pages outside the manifest are certificate-manager/acme-old.mdx and practical-zero-trust/README.mdx.

Facts I could not source and left out

• What the Console's Wi-Fi create form asks for today (the Quickstart uses the API instead).
• What a linked authority can and cannot do beyond "the platform manages its provisioners and admins" (melange concepts/trust.md); the boundary page says only that.
• Whether the docs site renders the kind: frontmatter field (the brief says it is ignored today).

🤖 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.}