Administration IA phase 3: Split the mixed concept/guide pages and write the landing pages

[jkodroff]

Phase 3 of the Administration IA restructure — the only phase with real content work.

Phases 1 and 2 put every page on the right shelf. Four pages are on a shelf only because they're two documents in one trench coat: a concept page with procedures bolted on. These are the pages that made the old IA look defensible — as long as a page is both a concept and a guide, no shelf is wrong. Splitting them is what makes the new structure actually true.

This phase also writes the landing pages that carry the topic groupings the old directory names used to provide.

All paths relative to content/docs/administration/.

Split the mixed pages

concepts/organizations.md

A concept page with twelve procedures bolted on. Current H2s: Organization Pages, Creating an organization, Joining an organization, Inviting members, Switching between organizations, Organization roles, Updating billing information, Changing the company name on invoices, Transferring stacks, Restoring a deleted stack, Deleting an organization, Deleting your account.

• Keep in concepts/organizations.md: what an organization is, how it relates to teams and accounts, organization roles.
• Move to guides/manage-organizations.md (new): create, join, invite, switch, transfer stacks, restore a deleted stack, delete an org, delete your account, billing info and invoice company name.
• Anchor links into the moved sections must survive — the current page's #creating-an-organization etc. are linked from elsewhere. Section anchors don't get Hugo aliases automatically; check inbound links before splitting.

concepts/audit-logs.md

Concept + procedure + event catalog in one file. Current H2/H3s: Overview, View audit logs, Automated export (→ AWS S3, → Microsoft Sentinel), Manual export (console, API, supported formats), List of audit log events.

• Keep in concepts/audit-logs.md: overview, what gets logged, viewing them.
• Move to guides/export-audit-logs/_index.md: manual export via console and API, supported formats. The per-destination pages (aws-s3, azure-sentinel) are already there from Phase 1 — this becomes their real landing page.
• Move to reference/audit-log-events.md (new): the event catalog.

concepts/customer-managed-keys.md

Same problem, smaller. Current H2s: Overview, Viewing Customer Managed Keys, Adding a Customer Managed Key (AWS KMS), Disabling a Customer Managed Key, Disabling All Customer Managed Keys.

• Keep in concepts/customer-managed-keys.md: what CMK is, key lifecycle, what disabling means for existing data.
• Move to guides/customer-managed-keys/_index.md: view, add, disable, disable all. The aws-kms page landed there in Phase 1.

concepts/rbac/teams.md

Mixed, smaller still. Current H2s: Creating a Team, Team Access Types, Role assignments, GitHub-based Teams, Team Entity Access Grants, Managing environment access via the REST API.

• Keep in concepts/rbac/teams.md: what a team is, access types, how role assignments and entity access grants accumulate.
• Move to guides/manage-teams.md (new): creating a team, GitHub-based teams, managing environment access via the REST API.

Write the landing pages

The old directory names — Access & Identity, Security & Compliance, Organizations & Teams — were genuinely useful for scanning. They come back as card groups on the section landing pages, not as URL segments.

• concepts/_index.md — button-cards grouped as Organizations & accounts (organizations, accounts, agent accounts) / Access & identity (access tokens, identity federation, RBAC) / Security & compliance (audit logs, customer-managed keys)
• guides/_index.md — grouped as Identity providers (SAML, SCIM, OIDC) / Organization management (manage organizations, manage teams, billing managers) / Security (least privilege, export audit logs, customer-managed keys)
• reference/_index.md — RBAC scopes, audit log events
• self-hosting/{get-started,concepts,guides,reference}/_index.md — real landing pages replacing the Phase 2 minimal ones; rebuild the deployment-option cards from the retired deployment-options/_index.md
• Update administration/_index.md cards to point at the new shelves

Follow the existing docs_home / button-cards frontmatter pattern already used by administration/_index.md and access-identity/_index.md.

New concept page

• concepts/identity-federation.md — a conceptual overview of how SAML, SCIM, and OIDC relate: what each one does, which you need, how they interact with RBAC. Absorbs the explanatory half of guides/saml/sso.md (moved in Phase 1); that page keeps the procedural half.

Also fold in

• esc/administration/_index.md is mostly a pointer list into Administration and links to /docs/administration/organizations-teams/teams/ — a redirect stub, so two hops today and three after Phase 1. Reduce it to its two genuinely ESC-specific pages (audit-logs, deletion-protection) and link out for the rest.

Acceptance

• 4 pages split; no content lost, everything re-linked
• Section anchors that moved between pages are checked against inbound links across content/docs/, content/product/, content/tutorials/
• 5 new pages written
• All landing pages carry topic-grouped cards so the old wayfinding survives
• Both light and dark mode checked on any new card/callout markup
• make lint passes; make lint-prose reviewed

Depends on Phases 1 and 2. Part of the Administration IA epic. Proposal with full rationale: https://claude.ai/code/artifact/3dfed61d-a02c-4feb-9f9d-c77d7b33accb