Add comprehensive historical alias verification and fix 8 missing aliases (#16295)

* Add comprehensive historical alias verification scripts

This adds a new set of scripts to verify ALL historical paths in git history
have proper aliases, catching missing aliases that the branch-diff verification
misses (pre-reorg moves, multi-hop moves, cross-branch moves).

New scripts:
- verify-all-historical-aliases.py: Scans complete git history (6 months)
  for all file moves, checks both frontmatter aliases and S3 redirects
- generate-historical-fixes.py: Parses verification output and generates
  fix data in JSON format
- apply-historical-fixes.py: Applies fixes by updating frontmatter aliases

Updated README.md with comprehensive documentation of the new workflow,
including when to use historical verification vs branch verification.

Fixes missing aliases from pre-reorg moves that happened on master before
the documentation reorganization branch was created.

Related: #16292, #16119

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Add git similarity detection to catch low-similarity renames

The original script missed files that were moved and significantly rewritten
in the same commit (recorded as DELETE+ADD instead of RENAME). This updates
the script to use git's -M30% flag, which detects renames even when files
are only 30% similar.

This now catches the missing OIDC files from the May 2024 documentation
revamp where content was significantly changed during the move:
- /docs/pulumi-cloud/access-management/oidc/provider/aws/
- /docs/pulumi-cloud/access-management/oidc/provider/azure/
- /docs/pulumi-cloud/access-management/oidc/provider/gcp/
- /docs/pulumi-cloud/access-management/oidc/provider/ (index)

Results:
- Before: 82 files with 82 missing aliases
- After: 92 files with 93 missing aliases (+10 files, +11 aliases)

Updated README to document the 30% similarity detection feature and
why it's necessary for catching content revamps.

Fixes #16292 (partially - provides tooling to detect the issue)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix false positives from development branch paths

The script was checking ALL branches (--all flag) including development
branches that were never merged to master. This caused 70% false positives
from paths that only existed during development and were never published.

Example: The CamSoper/content-reorg development branch had paths like
/docs/get-started/iac/gcp/ which were restructured to /docs/iac/get-started/gcp/
before merging. These dev-only paths don't need aliases because no external
links were ever created to them.

Changed from `--all` to `origin/master` to only check published history.

Results:
- Before: 93 missing aliases (65 false positives from /docs/get-started/*)
- After: 21 missing aliases (all legitimate)
- 77% reduction in false positives

The 21 remaining are real issues including the OIDC provider files from
the May 2024 documentation revamp.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Add missing historical aliases for 8 files

Applied fixes from the comprehensive historical alias verification, adding
8 missing aliases that the branch-diff verification missed:

Key fixes:
- OIDC provider files (AWS, Azure, GCP, index) from May 2024 documentation
  revamp where files were significantly rewritten (33-50% similarity)
- OIDC client kubernetes-eks file
- Developer portals templates file (including expected path that never existed)
- Deployments post-automation and API reference files

These were found using git's 30% similarity detection to catch low-similarity
renames (files moved and significantly rewritten in the same commit).

Also updated README.md to document the critical importance of reviewing
generated fixes for false positives before committing, including common
patterns to watch for and how to remove incorrect aliases.

Note: The original report found 21 missing aliases, but 13 were false
positives from similarity matching (Doppler/Infisical files, CLI command
pseudo-renames, etc.) and were manually removed.

Related: #16292, #16119

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix grammar error in meta_desc: 'Lean' -> 'Learn'

Co-authored-by: Cam Soper <CamSoper@users.noreply.github.com>

* Clarify prohibition on new files to specify that Markdown (.md) files must always end with a newline

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Cam Soper <CamSoper@users.noreply.github.com>

Author: 3 people

.gitignore

@@ -84,3 +84,7 @@ scripts/alias-verification/aliases-suspicious.txt
 scripts/alias-verification/deletes.txt
 scripts/alias-verification/renames.txt
 scripts/alias-verification/fixes-data.txt
+scripts/alias-verification/historical-aliases-correct.txt
+scripts/alias-verification/historical-aliases-missing.txt
+scripts/alias-verification/historical-aliases-report.txt
+scripts/alias-verification/historical-fixes.json

AGENTS.md

@@ -42,7 +42,7 @@ Do not substitute other tools or commands.
 ## Absolute Prohibitions
 
 - **Package manager**: Do **not** change `package.json` to use pnpm. Yarn/npm only.  
-- **New files**: Must always end with a newline.  
+- **Markdown (.md) files**: Must always end with a newline.  
 
 ---
 

content/docs/administration/access-identity/oidc-client/kubernetes-eks.md

@@ -14,8 +14,9 @@ menu:
     parent: openid-connect-client
     weight: 1
 aliases:
-- /docs/pulumi-cloud/oidc/client/kubernetes-eks/
-- /docs/pulumi-cloud/access-management/oidc-client/kubernetes-eks/
+  - /docs/pulumi-cloud/access-management/oidc-client/kubernetes-eks/
+  - /docs/pulumi-cloud/access-management/oidc/client/kubernetes-eks/
+  - /docs/pulumi-cloud/oidc/client/kubernetes-eks/
 ---
 
 This document outlines the steps required to configure Pulumi to accept Elastic Kubernetes Service (EKS) id_tokens to be exchanged for a personal access token. With this configuration, Kubernetes pods authenticate to Pulumi Cloud using OIDC tokens issued by EKS.

content/docs/deployments/deployments/oidc/_index.md

@@ -11,11 +11,12 @@ menu:
     weight: 60
     identifier: deployments-deployments-oidc
 aliases:
-- /docs/pulumi-cloud/oidc/
-- /docs/administration/access-identity/oidc/
-- /docs/pulumi-cloud/oidc/provider/
-- /docs/administration/access-identity/oidc/provider/
-- /docs/pulumi-cloud/deployments/oidc/
+  - /docs/administration/access-identity/oidc/
+  - /docs/administration/access-identity/oidc/provider/
+  - /docs/pulumi-cloud/access-management/oidc/provider/
+  - /docs/pulumi-cloud/deployments/oidc/
+  - /docs/pulumi-cloud/oidc/
+  - /docs/pulumi-cloud/oidc/provider/
 ---
 
 Pulumi Deployments supports OpenID Connect (OIDC) integration with popular cloud providers. In order for a Pulumi IaC operation like `update` or `preview` to work, the Pulumi CLI must be able to access credentials that will allow it to perform the necessary CRUD operations on the resources in your stack. Pulumi Deployments' OIDC integrations allow your your deployments to use dynamic, short-lived cloud credentials for supported clouds instead of static credentials which are less secure and difficult to rotate. This page explains how to set up OIDC for Pulumi Deployments to access resources in your cloud provider accounts.

content/docs/deployments/deployments/oidc/aws.md

@@ -11,13 +11,14 @@ menu:
     weight: 1
     identifier: deployments-deployments-oidc-aws
 aliases:
-- /docs/pulumi-cloud/deployments/oidc/aws/
-- /docs/guides/oidc/provider/aws
-- /docs/intro/deployments/oidc/provider/aws/
-- /docs/pulumi-cloud/deployments/oidc/provider/aws/
-- /docs/pulumi-cloud/oidc/provider/aws/
-- /docs/pulumi-cloud/oidc/aws/
-- /docs/administration/access-identity/oidc/provider/aws/
+  - /docs/administration/access-identity/oidc/provider/aws/
+  - /docs/guides/oidc/provider/aws
+  - /docs/intro/deployments/oidc/provider/aws/
+  - /docs/pulumi-cloud/access-management/oidc/provider/aws/
+  - /docs/pulumi-cloud/deployments/oidc/aws/
+  - /docs/pulumi-cloud/deployments/oidc/provider/aws/
+  - /docs/pulumi-cloud/oidc/aws/
+  - /docs/pulumi-cloud/oidc/provider/aws/
 ---
 
 {{% notes type="info" %}}

content/docs/deployments/deployments/oidc/azure.md

@@ -11,13 +11,14 @@ menu:
     weight: 2
     identifier: deployments-deployments-oidc-azure
 aliases:
-- /docs/pulumi-cloud/deployments/oidc/azure/
-- /docs/guides/oidc/provider/azure
-- /docs/intro/deployments/oidc/provider/azure/
-- /docs/pulumi-cloud/deployments/oidc/provider/azure/
-- /docs/pulumi-cloud/oidc/provider/azure/
-- /docs/pulumi-cloud/oidc/azure/
-- /docs/administration/access-identity/oidc/provider/azure/
+  - /docs/administration/access-identity/oidc/provider/azure/
+  - /docs/guides/oidc/provider/azure
+  - /docs/intro/deployments/oidc/provider/azure/
+  - /docs/pulumi-cloud/access-management/oidc/provider/azure/
+  - /docs/pulumi-cloud/deployments/oidc/azure/
+  - /docs/pulumi-cloud/deployments/oidc/provider/azure/
+  - /docs/pulumi-cloud/oidc/azure/
+  - /docs/pulumi-cloud/oidc/provider/azure/
 ---
 
 {{% notes type="info" %}}

content/docs/deployments/deployments/oidc/gcp.md

@@ -11,13 +11,14 @@ menu:
     weight: 3
     identifier: deployments-deployments-oidc-gcp
 aliases:
-- /docs/pulumi-cloud/deployments/oidc/gcp/
-- /docs/guides/oidc/provider/gcp
-- /docs/intro/deployments/oidc/provider/gcp/
-- /docs/pulumi-cloud/deployments/oidc/provider/gcp/
-- /docs/pulumi-cloud/oidc/provider/gcp/
-- /docs/pulumi-cloud/oidc/gcp/
-- /docs/administration/access-identity/oidc/provider/gcp/
+  - /docs/administration/access-identity/oidc/provider/gcp/
+  - /docs/guides/oidc/provider/gcp
+  - /docs/intro/deployments/oidc/provider/gcp/
+  - /docs/pulumi-cloud/access-management/oidc/provider/gcp/
+  - /docs/pulumi-cloud/deployments/oidc/gcp/
+  - /docs/pulumi-cloud/deployments/oidc/provider/gcp/
+  - /docs/pulumi-cloud/oidc/gcp/
+  - /docs/pulumi-cloud/oidc/provider/gcp/
 ---
 
 {{% notes type="info" %}}

content/docs/deployments/deployments/using/post-automation.md

@@ -5,7 +5,8 @@ title: "Post-Deployment Automation"
 h1: "Post-Deployment Automation"
 meta_image: /images/docs/meta-images/docs-meta.png
 aliases:
-- /docs/pulumi-cloud/deployments/using/post-automation/
+  - /docs/pulumi-cloud/deployments/reference/
+  - /docs/pulumi-cloud/deployments/using/post-automation/
 menu:
   deployments:
     parent: deployments-deployments-using

content/docs/idp/developer-portals/templates/_index.md

@@ -2,7 +2,7 @@
 title: Organization templates
 title_tag: Get started with organization templates
 h1: Building developer portals with organization templates
-meta_desc: Lean how to build template projects and configure them to work with your Pulumi organization.
+meta_desc: Learn how to build template projects and configure them to work with your Pulumi organization.
 menu:
   idp:
     name: Organization templates
@@ -12,6 +12,7 @@ menu:
 aliases:
   - /docs/idp/developer-portals/templates/
   - /docs/pulumi-cloud/developer-platforms/templates/
+  - /docs/pulumi-cloud/developer-portals/templates/
 ---
 
 {{% notes "info" %}}

content/docs/reference/cloud-rest-api/deployments/_index.md

@@ -7,14 +7,15 @@ menu:
         parent: cloud-rest-api
         weight: 4.5
 aliases:
-  - /docs/reference/cloud-rest-api/deployments/
   - /docs/deployments/deployments/api
   - /docs/deployments/deployments/api/
-  - /docs/reference/deployments-rest-api
-  - /docs/reference/deployments-rest-api/
   - /docs/intro/deployments/api
   - /docs/intro/deployments/api/
+  - /docs/pulumi-cloud/deployments/api/
   - /docs/pulumi-cloud/reference/deployments/
+  - /docs/reference/cloud-rest-api/deployments/
+  - /docs/reference/deployments-rest-api
+  - /docs/reference/deployments-rest-api/
 ---
 
 The Deployments API allows you to configure and manage Pulumi Deployments, which enable you to execute Pulumi updates and other operations through the Pulumi Cloud. With this API, you can configure deployment settings for your stacks, trigger deployments, view deployment status and logs, and manage deployment execution.