diff --git a/.vitepress/config.mts b/.vitepress/config.mts
index 2608442..837d4ac 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -54,8 +54,8 @@ export default defineConfig({
         text: 'Get started',
         items: [
           { text: 'GitHub quickstart', link: `${docsBase}/getting-started/github-quickstart.md` },
-          { text: 'Custom CI/CD', link: `${docsBase}/integrations/README.md#common-setup` },
-          { text: 'Bring your own agent', link: `${docsBase}/integrations/README.md#using-another-acp-cli` },
+          { text: 'Custom CI/CD', link: `${docsBase}/integrations/custom-ci.md` },
+          { text: 'Bring your own agent', link: `${docsBase}/providers/README.md` },
           { text: 'Configuration reference', link: `${docsBase}/reference/configuration.md` },
           { text: 'Troubleshooting', link: `${docsBase}/help/troubleshooting.md` }
         ]
@@ -72,21 +72,23 @@ export default defineConfig({
         items: [
           { text: 'GitHub Actions', link: `${docsBase}/integrations/github-actions.md` },
           { text: 'GitLab CI', link: `${docsBase}/integrations/gitlab-ci.md` },
-          { text: 'Azure Pipelines', link: `${docsBase}/integrations/azure-pipelines.md` }
+          { text: 'Azure Pipelines', link: `${docsBase}/integrations/azure-pipelines.md` },
+          { text: 'Custom CI/CD', link: `${docsBase}/integrations/custom-ci.md` }
         ]
       },
       {
         text: 'Providers',
         items: [
-          { text: 'Provider recipes', link: `${docsBase}/integrations/README.md#common-setup` },
-          { text: 'Provider model', link: `${docsBase}/reference/configuration.md#provider-model` },
-          { text: 'Generic ACP CLI', link: `${docsBase}/reference/configuration.md#generic-acp-cli` }
+          { text: 'Provider recipes', link: `${docsBase}/providers/README.md` },
+          { text: 'Provider model', link: `${docsBase}/concepts/providers-and-agents.md` },
+          { text: 'Generic ACP CLI', link: `${docsBase}/providers/custom-acp.md` }
         ]
       },
       {
         text: 'Guides',
         items: [
           { text: 'Verify first review', link: `${docsBase}/getting-started/verify-first-review.md` },
+          { text: 'Secrets and fork PRs', link: `${docsBase}/guides/secrets-and-fork-prs.md` },
           { text: 'Examples gallery', link: examplesBase }
         ]
       },
@@ -104,7 +106,7 @@ export default defineConfig({
         text: 'Help',
         items: [
           { text: 'Troubleshooting', link: `${docsBase}/help/troubleshooting.md` },
-          { text: 'Fork pull requests and secrets', link: `${docsBase}/help/troubleshooting.md#fork-pull-requests-and-secrets` }
+          { text: 'FAQ', link: `${docsBase}/help/faq.md` }
         ]
       }
     ],
diff --git a/docs.md b/docs.md
index 68d08f7..4b39c5e 100644
--- a/docs.md
+++ b/docs.md
@@ -5,10 +5,11 @@ DiffPal technical documentation lives in the main repository and is the canonica
 ## Start Here
 
 - [GitHub quickstart](https://github.com/diffpal/diffpal/blob/main/docs/getting-started/github-quickstart.md)
-- [Custom CI/CD](https://github.com/diffpal/diffpal/blob/main/docs/integrations/README.md#common-setup)
-- [Bring your own agent](https://github.com/diffpal/diffpal/blob/main/docs/integrations/README.md#using-another-acp-cli)
+- [Custom CI/CD](https://github.com/diffpal/diffpal/blob/main/docs/integrations/custom-ci.md)
+- [Bring your own agent](https://github.com/diffpal/diffpal/blob/main/docs/providers/README.md)
 - [Configuration reference](https://github.com/diffpal/diffpal/blob/main/docs/reference/configuration.md)
 - [Troubleshooting](https://github.com/diffpal/diffpal/blob/main/docs/help/troubleshooting.md)
+- [FAQ](https://github.com/diffpal/diffpal/blob/main/docs/help/faq.md)
 
 ## Browse By Goal
 
@@ -16,9 +17,10 @@ DiffPal technical documentation lives in the main repository and is the canonica
 | --- | --- |
 | Understand the review flow | [How DiffPal works](https://github.com/diffpal/diffpal/blob/main/docs/concepts/how-diffpal-works.md) |
 | Set up GitHub, GitLab, or Azure | [Integrations](https://github.com/diffpal/diffpal/blob/main/docs/integrations/README.md) |
-| Choose or configure a provider | [Provider configuration](https://github.com/diffpal/diffpal/blob/main/docs/reference/configuration.md#provider-model) |
+| Choose or configure a provider | [Providers](https://github.com/diffpal/diffpal/blob/main/docs/providers/README.md) |
 | Consume artifacts | [Artifacts reference](https://github.com/diffpal/diffpal/blob/main/docs/reference/artifacts.md) |
 | Check supported outputs | [Support matrix](https://github.com/diffpal/diffpal/blob/main/docs/reference/support-matrix.md) |
+| Secure secrets and fork PRs | [Secrets and fork PRs](https://github.com/diffpal/diffpal/blob/main/docs/guides/secrets-and-fork-prs.md) |
 
 ## More Resources
 
diff --git a/index.md b/index.md
index df79049..3001bc7 100644
--- a/index.md
+++ b/index.md
@@ -75,5 +75,5 @@ DiffPal sends review requests to the provider you configure. Depending on that p
 ## Start Reviewing
 
 - [Start with GitHub Actions](https://github.com/diffpal/diffpal/blob/main/docs/getting-started/github-quickstart.md)
-- [Use another CI/CD system](https://github.com/diffpal/diffpal/blob/main/docs/integrations/README.md#common-setup)
-- [Bring your own agent](https://github.com/diffpal/diffpal/blob/main/docs/integrations/README.md#using-another-acp-cli)
+- [Use another CI/CD system](https://github.com/diffpal/diffpal/blob/main/docs/integrations/custom-ci.md)
+- [Bring your own agent](https://github.com/diffpal/diffpal/blob/main/docs/providers/README.md)
diff --git a/security.md b/security.md
index af74182..aa9cc4b 100644
--- a/security.md
+++ b/security.md
@@ -12,6 +12,6 @@ DiffPal sends review requests to the provider you configure. Depending on that p
 
 ## Canonical References
 
-- [GitHub quickstart security notes](https://github.com/diffpal/diffpal/blob/main/docs/getting-started/github-quickstart.md#2-add-secret)
-- [Fork pull requests and secrets](https://github.com/diffpal/diffpal/blob/main/docs/help/troubleshooting.md#fork-pull-requests-and-secrets)
+- [GitHub quickstart security notes](https://github.com/diffpal/diffpal/blob/main/docs/getting-started/github-quickstart.md#2-add-the-provider-secret)
+- [Secrets and fork PRs](https://github.com/diffpal/diffpal/blob/main/docs/guides/secrets-and-fork-prs.md)
 - [Platform authentication reference](https://github.com/diffpal/diffpal/blob/main/docs/reference/configuration.md#platform-auth)