Epic: Restructure the Administration docs against the standard IA

[jkodroff]

Realign /docs/administration/ against the standard docs IA — organize it by document type (get started, concepts, guides, reference) rather than by topic.

📄 Full proposal with the page-by-page mapping table: https://claude.ai/code/artifact/3dfed61d-a02c-4feb-9f9d-c77d7b33accb

The problem

Six product sections converge on the same shelf labels:

Section	Subsections
iac/	get-started, concepts, guides, operations
esc/	get-started, concepts, guides, operations, integrations
deployments/	get-started, concepts, guides, operations
idp/	concepts, guides, integrations
insights/	discovery (with its own get-started), policy
administration/	onboarding-guide, organizations-teams, access-identity, security-compliance, self-hosting

Administration's five buckets are topics, not document types. Concrete costs:

• Explanation and procedure sit undifferentiated. access-identity/ holds the RBAC permission model (5 pages of pure concept), nine per-IdP SAML setup walkthroughs, and four pages of scope lookup tables. Someone learning how permissions accumulate and someone wiring up Okta land in the same list.
• Reference material has nowhere to go. rbac/scopes/org-settings.md is 2,400 words of table, shelved as if it were a concept page.
• The topic buckets aren't clean either. Teams live at access-identity/rbac/teams, but organizations-teams/ is named for them and holds only a redirect stub.
• Self-hosting is product-sized with no internal IA. 25 pages under components/, deployment-options/, operations/ — one document type and two topics.

Proposed structure

administration/
├── get-started/          ← onboarding-guide/ (already a linear path)
├── concepts/             org + access model, RBAC
├── guides/               SAML, SCIM, OIDC, audit-log export, CMK, least privilege
├── reference/            RBAC scope tables, audit event catalog
└── self-hosting/
    ├── get-started/
    ├── concepts/         architecture, components/, network-requirements
    ├── guides/           deploy-on-*, air-gapped, configure-saml-sso
    ├── operations/       unchanged — already the right shelf
    └── reference/        changelog

Decisions worth reviewing

• Topic groupings survive as card groups, not URL segments. Identity / security / org management are useful for scanning, so they move to the concepts/ and guides/ landing pages and to menu weight ordering. Readers keep the wayfinding; URLs stop lying about what kind of page they open.
• No top-level operations/. For a hosted control plane, the entire section is operations — a peer folder by that name would collect an arbitrary handful. Self-hosting keeps its operations/ because there it means something specific: running the software you installed. If we want the label for symmetry, the natural occupants are audit-log export, token expiry policy, and key rotation.
• Self-hosting stays nested rather than dissolving into the top-level shelves. Distinct audience doing a distinct job; precedent in insights/discovery/get-started/. The alternative — promoting it to a top-level docs section — is a bigger conversation than this epic.
• RBAC scope tables move to reference/, the RBAC model stays in concepts/. The four scopes/* pages are enumerations you consult, not explanations you read. Risk: one extra click between "what's a scope" and "which scopes exist."
• Four pages need splitting, not moving. organizations.md is a concept with twelve procedures bolted on; audit-logs/_index.md is concept + procedure + event catalog in one file; same problem smaller in customer-managed-keys/_index.md and rbac/teams.md. These are the pages that made the current IA look defensible — as long as a page is both a concept and a guide, no shelf is wrong.

Phasing

Sixty-four file moves. Every one needs a Hugo alias or it costs search ranking, so this ships as three PRs rather than one. Phases 1 and 2 are pure git mv + alias with zero prose edits, which keeps them reviewable.

Phase	Scope	Content work
#21052	Re-shelve the SaaS side	46 moves, 0 content changes
#21053	Give self-hosting the same shelves	18 moves, 9 pages stay put
#21054	Split the mixed pages, write the landing pages	4 splits, 5 new pages

⚠️ The real risk is aliases, not moves. Administration pages carry deep alias chains already — self-hosting/_index.md alone lists six historical paths back to /docs/guides/self-hosted/. Every one has to survive the move on top of the new alias. Use /move-doc, which injects and verifies them, and run a full make lint plus alias verification before each merge.

Cleanups to fold in

Found while mapping. None blocks the restructure; all are cheaper to fix during it.

• organizations-teams/teams.md is a redirect stub whose redirect_to points at /docs/pulumi-cloud/access-management/rbac/teams — a legacy path only reachable through an alias. Should point at the current canonical URL.
• SAML is documented twice: access-identity/saml/ (nine pages) and self-hosting/saml-sso.md (standalone, 492 words). Reconcile into one guide with a self-hosted section.
• esc/administration/_index.md links to /docs/administration/organizations-teams/teams/ — the stub above, so two hops today and three after the move. That landing page is mostly a pointer list into Administration and could reduce to its two genuinely ESC-specific pages.
• Menu label casing is inconsistent: "Self-Hosting" in the parent card vs. "Self-hosting" in the page title; "Network reqs" as a link title for network.md.
• Six of eight self-hosted deployment pages are named *-hosted while two aren't (local-docker, quickstart-docker-compose). The proposed deploy-on-* naming makes the set consistent and reads better in the sidebar.
• security-compliance/least-privilege/ is a directory containing only _index.md. Should be a single file wherever it lands.