docs: Updates & polishes (#1634)

mohab-sameh · web-flow · commit a7a559833f77 · 2025-07-22T19:45:21.000+03:00
diff --git a/apps/docs/cli/cli-reference.mdx b/apps/docs/cli/cli-reference.mdx
@@ -43,8 +43,8 @@ For more details on building and running workflows, see the [Workflows documenta
 
 ## Advanced Concepts
 
-- **Workflows:** Orchestrate complex, multi-step codemod processes. [Learn more ->](#cli-command-reference)
-- **jssg:** Run JavaScript/TypeScript codemods using the high-performance ast-grep engine. [See jssg reference ->](#codemod%40next-jssg)
+- **Workflows:** Orchestrate complex, multi-step codemod processes.
+- **jssg:** Run JavaScript/TypeScript codemods using the high-performance ast-grep engine.
 
 ---
 
@@ -56,7 +56,7 @@ Codemod CLI (new) is accessible using the `npx codemod@next` command. The follow
 
 Manage and execute workflow YAMLs.
 
-**`workflow run`**
+#### `workflow run`
 
 Run a workflow.
 
@@ -70,7 +70,7 @@ npx codemod@next workflow run -w <workflow.yaml|directory> [--param key=value]
   Workflow parameters (format: key=value).
 </ResponseField>
 
-**`workflow resume`**
+#### `workflow resume`
 
 Resume a paused workflow.
 
@@ -87,7 +87,7 @@ npx codemod@next workflow resume -i <ID> [-t <TASK>] [--trigger-all]
   Trigger all awaiting tasks.
 </ResponseField>
 
-**`workflow validate`**
+#### `workflow validate`
 
 Validate a workflow file.
 
@@ -124,7 +124,7 @@ npx codemod@next workflow validate -w <workflow.yaml>
   - **State consistency**: Whether state updates are logically sound
   </Accordion>
 
-**`workflow status`**
+#### `workflow status`
 
 Show workflow run status.
 
@@ -135,7 +135,7 @@ npx codemod@next workflow status -i <ID>
   Workflow run ID.
 </ResponseField>
 
-**`workflow list`**
+#### `workflow list`
 
 List workflow runs.
 
@@ -146,7 +146,7 @@ npx codemod@next workflow list [-l <LIMIT>]
   Number of workflow runs to show. (default: 10)
 </ResponseField>
 
-**`workflow cancel`**
+#### `workflow cancel`
 
 Cancel a workflow run.
 
@@ -200,7 +200,7 @@ jssg is a toolkit for running JavaScript/TypeScript codemods using the high-perf
   </Step>
 </Steps>
 
-**`jssg run`**
+#### `jssg run`
 
 Run a jssg codemod.
 
@@ -232,7 +232,7 @@ npx codemod@next jssg run <codemod_file> <target_directory> [options]
   Perform a dry-run to see the changes without applying them.
 </ResponseField>
 
-**`jssg test`**
+#### `jssg test`
 
 Test a jssg codemod using before/after fixtures.
 
@@ -500,15 +500,15 @@ npx codemod@next search --format json next
 
 Manage the local package cache for codemod packages.
 
-**`cache info`**
+#### `cache info`
 
 Show cache information and statistics.
 
 ```bash
 npx codemod@next cache info
 ```
 
-**`cache list`**
+#### `cache list`
 
 List cached packages.
 
@@ -519,7 +519,7 @@ npx codemod@next cache list [--detailed]
   Show package details.
 </ResponseField>
 
-**`cache clear`**
+#### `cache clear`
 
 Clear cache for a specific package, or all packages.
 
@@ -533,7 +533,7 @@ npx codemod@next cache clear [PACKAGE] [--all]
   Clear all cached packages.
 </ResponseField>
 
-**`cache prune`**
+#### `cache prune`
 
 Prune old or unused cache entries.
 
diff --git a/apps/docs/cli/workflows.mdx b/apps/docs/cli/workflows.mdx
@@ -17,7 +17,7 @@ Codemod Workflows are self-hostable automations designed for running large-scale
 - **Parallel scheduling** — independent nodes run when dependencies allow
 - **Host-shell execution** — commands run directly on your machine (container runtimes on the roadmap)
 
-Codemod Workflows can be run using [Codemod CLI](/cli/cli-reference) or [Codemod Platform](/platform/workflows).
+Codemod Workflows can be run using [Codemod CLI](/cli/cli-reference) or [Codemod Platform](/migrations).
 
 ---
 
@@ -697,11 +697,8 @@ nodes:
 
 ## Next Steps
 
-<CardGroup cols={2}>
+<CardGroup cols={1}>
   <Card title="Codemod CLI Reference" icon="terminal" href="/cli/cli-reference">
     Explore the full command and option reference for Codemod CLI.
   </Card>
-  <Card title="jssg: JavaScript ast-grep" icon="js" href="/cli/jssg">
-    Perform fast, AST-based searches & transformations using a grep-like interface.
-  </Card>
 </CardGroup>
diff --git a/apps/docs/codemod-studio.mdx b/apps/docs/codemod-studio.mdx
@@ -92,6 +92,10 @@ To run codemods, you can:
   </Step>
 </Steps>
 
+<Info>
+  Prefer running codemods from your terminal or CI? See our [CLI](/cli/cli-reference) guide for scripting and automating codemods locally or in CI.
+</Info>
+
 ## Tips for building better codemods
 
 1. **Clarity is Key**: Try to prompt clear requirements when using Codemod AI. Ensure that the transformation logic is clear for both humans and AI. Well-defined logic leads to more accurate codemods.
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
@@ -20,13 +20,7 @@
         "groups": [
           {
             "group": "Quickstart",
-            "pages": [
-              "introduction",
-              "platform/plan",
-              "platform/automate",
-              "platform/orchestrate",
-              "platform/track"
-            ]
+            "pages": ["introduction"]
           },
           {
             "group": "Codemod Platform",
@@ -38,11 +32,7 @@
           },
           {
             "group": "Quick Links",
-            "pages": [
-              "external-links/codemod-platform",
-              "external-links/codemod-studio",
-              "external-links/codemod-registry"
-            ]
+            "pages": ["external-links/codemod-registry"]
           },
           {
             "group": "Other Resources",
@@ -113,6 +103,22 @@
     {
       "source": "/more-resources/legal/terms-and-conditions",
       "destination": "https://codemod.com/terms-and-conditions"
+    },
+    {
+      "source": "/platform/plan",
+      "destination": "/migrations"
+    },
+    {
+      "source": "/platform/automate",
+      "destination": "/codemod-studio"
+    },
+    {
+      "source": "/platform/orchestrate",
+      "destination": "/migrations"
+    },
+    {
+      "source": "/platform/track",
+      "destination": "/insights"
     }
   ],
   "contextual": {
diff --git a/apps/docs/migrations.mdx b/apps/docs/migrations.mdx
@@ -9,8 +9,16 @@ Migration Campaigns let engineering teams orchestrate sweeping code changes—fr
 
 By combining Codemod’s AI-powered runbooks with deterministic automations, campaigns dramatically lower migration cost and risk while giving you full visibility into progress.
 
-<Tip>
+<Info>
   Migration Campaigns are designed for [enterprise](https://codemod.com/pricing) engingeering teams. To start a new migration campaign, simply [get in touch with us](https://go.codemod.com/contact) and we'll add the requested migration to your dashboard.
+</Info>
+
+## Before you start: plan with Insights
+
+Use **[Codemod Insights](/insights)** dashboards to measure how widespread a pattern is, estimate effort, and decide which repositories to include in your campaign. Once priorities are clear, spin up a new Migration Campaign and execute with confidence.
+
+<Tip>
+  Not sure where to begin? [Contact us](https://go.codemod.com/contact) and we’ll help surface high-impact, low-effort migrations you can tackle right away.
 </Tip>
 
 ## Running a Migration Campaign
