docs: archive migration tooling and assessment doc

Adds migration/ at the repo root as a historical record of the 2026-05-05
docs redesign. Contents:

- ASSESSMENT.md — planning and decision log, including the three-repo deploy
  flow, redirect table, SEO additions, and what was actually executed.
- migrate.py — one-shot Python script that ported PR #117 content into
  docs/docs/, normalized frontmatter, dropped numeric prefixes, generated
  _category_.json files.
- fixup_links.py — one-shot link-fixup pass that fixed 27 internal markdown
  links across 9 files after migrate.py.
- README.md — orientation for future readers, plus a clear DO-NOT-RE-RUN
  warning (migrate.py would wipe the manually-authored Contrast page and
  revert the welcome doc's slug: /).

Lives at the repo root rather than docs/migration/ so Docusaurus does not
treat these files as published pages.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dhafley

docs/api/api-overview.md

@@ -58,29 +58,29 @@ repositories = response.json()
 
 ## Rate limits
 
-| Tier | Requests per minute | Burst |
-|------|-------------------|-------|
-| Standard | 60 | 10 |
-| Enterprise | 300 | 50 |
+| Tier       | Requests per minute | Burst |
+| ---------- | ------------------- | ----- |
+| Standard   | 60                  | 10    |
+| Enterprise | 300                 | 50    |
 
 Rate-limited responses return `429 Too Many Requests` with a `Retry-After` header indicating seconds until the next available request window.
 
 ## Available endpoints
 
-| Category | Method | Endpoint | Description |
-|----------|--------|----------|-------------|
-| Repositories | `GET` | `/repositories` | List repositories connected to your organization |
-| Repositories | `GET` | `/repositories/{id}` | Get repository configuration and status |
-| Repositories | `PATCH` | `/repositories/{id}` | Update repository settings |
-| Fixes | `GET` | `/repositories/{id}/fixes` | List fix results for a repository |
-| Fixes | `GET` | `/fixes/{id}` | Get fix details including CodeTF output |
-| Scans | `GET` | `/repositories/{id}/scans` | List scan history |
-| Scans | `POST` | `/repositories/{id}/scans` | Trigger a new scan |
-| Triage | `GET` | `/repositories/{id}/findings` | List triaged findings |
-| Triage | `GET` | `/findings/{id}` | Get finding details and triage classification |
-| Webhooks | `POST` | `/webhooks` | Register a webhook endpoint |
-| Webhooks | `GET` | `/webhooks` | List registered webhooks |
-| Webhooks | `DELETE` | `/webhooks/{id}` | Remove a webhook |
+| Category     | Method   | Endpoint                      | Description                                      |
+| ------------ | -------- | ----------------------------- | ------------------------------------------------ |
+| Repositories | `GET`    | `/repositories`               | List repositories connected to your organization |
+| Repositories | `GET`    | `/repositories/{id}`          | Get repository configuration and status          |
+| Repositories | `PATCH`  | `/repositories/{id}`          | Update repository settings                       |
+| Fixes        | `GET`    | `/repositories/{id}/fixes`    | List fix results for a repository                |
+| Fixes        | `GET`    | `/fixes/{id}`                 | Get fix details including CodeTF output          |
+| Scans        | `GET`    | `/repositories/{id}/scans`    | List scan history                                |
+| Scans        | `POST`   | `/repositories/{id}/scans`    | Trigger a new scan                               |
+| Triage       | `GET`    | `/repositories/{id}/findings` | List triaged findings                            |
+| Triage       | `GET`    | `/findings/{id}`              | Get finding details and triage classification    |
+| Webhooks     | `POST`   | `/webhooks`                   | Register a webhook endpoint                      |
+| Webhooks     | `GET`    | `/webhooks`                   | List registered webhooks                         |
+| Webhooks     | `DELETE` | `/webhooks/{id}`              | Remove a webhook                                 |
 
 For webhook event types and payload schemas, see [Webhooks](/api/webhooks).
 
@@ -98,14 +98,14 @@ All error responses use a consistent JSON structure:
 }
 ```
 
-| Status code | Meaning |
-|-------------|---------|
-| `400` | Bad request. Check request body and parameters. |
-| `401` | Invalid or missing API token. |
-| `403` | Token does not have permission for this resource. |
-| `404` | Resource not found. |
-| `429` | Rate limit exceeded. Retry after the interval in the `Retry-After` header. |
-| `500` | Internal server error. Retry with exponential backoff. Include the `request_id` in support tickets. |
+| Status code | Meaning                                                                                             |
+| ----------- | --------------------------------------------------------------------------------------------------- |
+| `400`       | Bad request. Check request body and parameters.                                                     |
+| `401`       | Invalid or missing API token.                                                                       |
+| `403`       | Token does not have permission for this resource.                                                   |
+| `404`       | Resource not found.                                                                                 |
+| `429`       | Rate limit exceeded. Retry after the interval in the `Retry-After` header.                          |
+| `500`       | Internal server error. Retry with exponential backoff. Include the `request_id` in support tickets. |
 
 ## Quick start
 

docs/api/changelog.md

@@ -123,12 +123,12 @@ Categories are omitted when a release has no entries of that type.
 
 Pixee Enterprise Server releases are versioned independently of the Pixee cloud platform. The Helm chart version (e.g., v5.6.0) and embedded cluster version share the same release notes.
 
-| Deployment Model | Version Source | Update Method |
-|-----------------|---------------|---------------|
-| Cloud (SaaS) | Automatic | Managed by Pixee |
-| Embedded Cluster | KOTS admin console | One-click update via admin console |
+| Deployment Model      | Version Source     | Update Method                         |
+| --------------------- | ------------------ | ------------------------------------- |
+| Cloud (SaaS)          | Automatic          | Managed by Pixee                      |
+| Embedded Cluster      | KOTS admin console | One-click update via admin console    |
 | Helm / BYO Kubernetes | Helm chart version | `helm upgrade` with new chart version |
-| Air-gapped | Offline bundle | Download bundle, apply via KOTS |
+| Air-gapped            | Offline bundle     | Download bundle, apply via KOTS       |
 
 For upgrade procedures and troubleshooting, see [Enterprise Deployment](/enterprise/deployment) and [Enterprise Troubleshooting](/enterprise/troubleshooting).
 

docs/api/codetf.md

@@ -14,22 +14,22 @@ CodeTF (Code Transformation Format) is an open specification created by Pixee fo
 
 ## What is CodeTF?
 
-Existing standards describe security findings (SARIF), dependencies (SBOM), and vulnerabilities (CVE/CWE). No standard existed for describing *what an automated fix actually did to your code*. CodeTF fills that gap.
+Existing standards describe security findings (SARIF), dependencies (SBOM), and vulnerabilities (CVE/CWE). No standard existed for describing _what an automated fix actually did to your code_. CodeTF fills that gap.
 
 CodeTF is the output format. SARIF is the input format. A scanner produces a SARIF file describing the problem. Pixee consumes that SARIF, generates a fix, and produces a CodeTF document describing the solution.
 
 CodeTF is an open specification. Any tool can produce or consume CodeTF documents. The schema is publicly available on [GitHub](https://github.com/pixee/codemodder-specs).
 
 ## CodeTF vs SARIF
 
-| Dimension | SARIF | CodeTF |
-|-----------|-------|--------|
-| Purpose | Describes findings (problems) | Describes fixes (changes) |
-| Direction | Scanner output | Remediation output |
-| Content | Vulnerability location and metadata | Code diffs, rationale, and validation |
-| Standard body | OASIS | Open specification by Pixee |
-| Use case | Input to Pixee | Output from Pixee |
-| Data model | Runs, results, locations | Run metadata, results, changesets |
+| Dimension     | SARIF                               | CodeTF                                |
+| ------------- | ----------------------------------- | ------------------------------------- |
+| Purpose       | Describes findings (problems)       | Describes fixes (changes)             |
+| Direction     | Scanner output                      | Remediation output                    |
+| Content       | Vulnerability location and metadata | Code diffs, rationale, and validation |
+| Standard body | OASIS                               | Open specification by Pixee           |
+| Use case      | Input to Pixee                      | Output from Pixee                     |
+| Data model    | Runs, results, locations            | Run metadata, results, changesets     |
 
 ## Schema overview
 
@@ -65,50 +65,50 @@ CodeTF Document
 
 ### Top-level fields
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `version` | string | Yes | Schema version. Current: `"3.0.0"` |
-| `run` | object | Yes | Execution context for the transformation run |
-| `results` | array | Yes | Array of transformation results. May be empty if no fixes were generated. |
+| Field     | Type   | Required | Description                                                               |
+| --------- | ------ | -------- | ------------------------------------------------------------------------- |
+| `version` | string | Yes      | Schema version. Current: `"3.0.0"`                                        |
+| `run`     | object | Yes      | Execution context for the transformation run                              |
+| `results` | array  | Yes      | Array of transformation results. May be empty if no fixes were generated. |
 
 ### Run object
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `run.vendor` | string | Yes | Vendor name (e.g., `"pixee"`) |
-| `run.tool` | string | Yes | Engine identifier (e.g., `"codemodder-python"`) |
-| `run.elapsed` | string | No | ISO 8601 duration or human-readable processing time |
-| `run.commandLine` | string | No | Command used to invoke the transformation |
+| Field             | Type   | Required | Description                                         |
+| ----------------- | ------ | -------- | --------------------------------------------------- |
+| `run.vendor`      | string | Yes      | Vendor name (e.g., `"pixee"`)                       |
+| `run.tool`        | string | Yes      | Engine identifier (e.g., `"codemodder-python"`)     |
+| `run.elapsed`     | string | No       | ISO 8601 duration or human-readable processing time |
+| `run.commandLine` | string | No       | Command used to invoke the transformation           |
 
 ### Result object
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `codemod` | string | Yes | Unique codemod identifier (e.g., `"pixee:python/secure-random"`) |
-| `summary` | string | Yes | One-line human-readable fix description |
-| `description` | string | Yes | Detailed explanation of what the fix does and why |
-| `references` | array | No | External references: `{"url": "https://cwe.mitre.org/...", "description": "CWE-330"}` |
-| `properties` | object | No | Arbitrary key-value metadata for custom integrations |
-| `changeset` | array | Yes | Array of file-level changes (at least one entry per result) |
-| `detectionTool` | string | No | Scanner that detected the original finding |
-| `fixedFindings` | array | No | Array of SARIF finding references this fix resolves |
+| Field           | Type   | Required | Description                                                                           |
+| --------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
+| `codemod`       | string | Yes      | Unique codemod identifier (e.g., `"pixee:python/secure-random"`)                      |
+| `summary`       | string | Yes      | One-line human-readable fix description                                               |
+| `description`   | string | Yes      | Detailed explanation of what the fix does and why                                     |
+| `references`    | array  | No       | External references: `{"url": "https://cwe.mitre.org/...", "description": "CWE-330"}` |
+| `properties`    | object | No       | Arbitrary key-value metadata for custom integrations                                  |
+| `changeset`     | array  | Yes      | Array of file-level changes (at least one entry per result)                           |
+| `detectionTool` | string | No       | Scanner that detected the original finding                                            |
+| `fixedFindings` | array  | No       | Array of SARIF finding references this fix resolves                                   |
 
 ### Changeset object
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `path` | string | Yes | File path relative to repository root |
-| `diff` | string | Yes | Unified diff of the change |
-| `changes` | array | No | Line-level descriptions of individual changes |
-| `ai` | boolean | No | `true` if AI generated this change; `false` or absent for deterministic codemods |
+| Field     | Type    | Required | Description                                                                      |
+| --------- | ------- | -------- | -------------------------------------------------------------------------------- |
+| `path`    | string  | Yes      | File path relative to repository root                                            |
+| `diff`    | string  | Yes      | Unified diff of the change                                                       |
+| `changes` | array   | No       | Line-level descriptions of individual changes                                    |
+| `ai`      | boolean | No       | `true` if AI generated this change; `false` or absent for deterministic codemods |
 
 ### Change object
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `lineNumber` | integer | Yes | Line number in the modified file |
-| `description` | string | Yes | What changed at this line |
-| `properties` | object | No | Additional per-change metadata |
+| Field         | Type    | Required | Description                      |
+| ------------- | ------- | -------- | -------------------------------- |
+| `lineNumber`  | integer | Yes      | Line number in the modified file |
+| `description` | string  | Yes      | What changed at this line        |
+| `properties`  | object  | No       | Additional per-change metadata   |
 
 ## Complete example
 
@@ -220,10 +220,10 @@ with open("audit-trail.csv", "w", newline="") as f:
 
 CodeTF uses semantic versioning. The current schema version is `3.0.0`.
 
-| Version | Status | Notes |
-|---------|--------|-------|
-| 3.0.0 | Current | Pydantic-modeled schema, fix-quality ratings, package actions |
-| 2.0.0 | Supported | Previous schema version |
+| Version | Status    | Notes                                                         |
+| ------- | --------- | ------------------------------------------------------------- |
+| 3.0.0   | Current   | Pydantic-modeled schema, fix-quality ratings, package actions |
+| 2.0.0   | Supported | Previous schema version                                       |
 
 Breaking changes between major versions are documented in the [Changelog](/api/changelog). CodeTF documents always include a `version` field so consumers can branch on schema version at parse time.