docs: fix broken and naked relative links (#25825)

Several relative links in the docs pointed at pages that no longer exist
or rendered incorrectly on coder.com.

Fixes:

- `start/first-template.md`: IDE links repointed from the removed
`../ides.md` / `../ides/web-ides.md` to their current homes under
`user-guides/workspace-access/`.
- `tutorials/example-guide.md`: contributing link repointed to
`../about/contributing/documentation.md`.
- `about/contributing/backend.md`: the `migrations/testdata/fixtures`
and `full_dumps` references (and the `000024_example.up.sql` example)
used relative paths that escape `docs/` and render as bogus
`/docs/coderd/...` routes on the site. Normalized to the canonical
`github.com/coder/coder/(blob|tree)/main/...` form already used by ~120
other source links in the docs.
- Normalized extensionless directory links (`ai-coder/ai-gateway`,
`user-guides/workspace-access`, `install`) to their `/index.md` targets
for consistency with the rest of the docs.

This class of bug is invisible to the local doc checks (`make
lint/markdown` / `pnpm check-docs` only run markdownlint + table
formatting); only CI's Linkspector job validates link targets. Found via
a relative-link audit while investigating the docs preview on #25816.

Source-link version-awareness (so older docs versions don't all point at
`main`) is tracked separately in DOCS-268 and will be handled in the
coder.com render layer.


Linear: DOCS-278

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/about/contributing/backend.md

@@ -169,9 +169,9 @@ There are two types of fixtures that are used to test that migrations don't
 break existing Coder deployments:
 
 * Partial fixtures
-  [`migrations/testdata/fixtures`](../../../coderd/database/migrations/testdata/fixtures)
+  [`migrations/testdata/fixtures`](https://github.com/coder/coder/tree/main/coderd/database/migrations/testdata/fixtures)
 * Full database dumps
-  [`migrations/testdata/full_dumps`](../../../coderd/database/migrations/testdata/full_dumps)
+  [`migrations/testdata/full_dumps`](https://github.com/coder/coder/tree/main/coderd/database/migrations/testdata/full_dumps)
 
 Both types behave like database migrations (they also
 [`migrate`](https://github.com/golang-migrate/migrate)). Their behavior mirrors
@@ -194,7 +194,7 @@ To add a new partial fixture, run the following command:
 ```
 
 Then add some queries to insert data and commit the file to the repo. See
-[`000024_example.up.sql`](../../../coderd/database/migrations/testdata/fixtures/000024_example.up.sql)
+[`000024_example.up.sql`](https://github.com/coder/coder/blob/main/coderd/database/migrations/testdata/fixtures/000024_example.up.sql)
 for an example.
 
 To create a full dump, run a fully fledged Coder deployment and use it to

docs/admin/infrastructure/architecture.md

@@ -142,7 +142,7 @@ as OpenAI and Anthropic. Users authenticate through Coder instead of managing se
 provider API keys. All prompts, token usage, and tool invocations are recorded
 for compliance and cost tracking.
 
-Learn more: [AI Gateway](../../ai-coder/ai-gateway)
+Learn more: [AI Gateway](../../ai-coder/ai-gateway/index.md)
 
 ### Agent Firewall
 

docs/ai-coder/tasks-core-principles.md

@@ -17,7 +17,7 @@ Coder Tasks is Coder's platform for managing coding agents. With Coder Tasks, yo
 
 ![Tasks UI](../images/guides/ai-agents/tasks-ui.png)Coder Tasks Dashboard view to see all available tasks.
 
-Coder Tasks allows you and your organization to build and automate workflows to fully leverage AI. Tasks operate through Coder Workspaces. We support interacting with an agent through the Task UI and CLI. Some Tasks can also be accessed through the Coder Workspace IDE; see [connect via an IDE](../user-guides/workspace-access).
+Coder Tasks allows you and your organization to build and automate workflows to fully leverage AI. Tasks operate through Coder Workspaces. We support interacting with an agent through the Task UI and CLI. Some Tasks can also be accessed through the Coder Workspace IDE; see [connect via an IDE](../user-guides/workspace-access/index.md).
 
 ## Why Use Tasks?
 

docs/ai-coder/tasks.md

@@ -11,7 +11,7 @@ Coder Tasks is an interface for running & managing coding agents such as Claude
 
 ![Tasks UI](../images/guides/ai-agents/tasks-ui.png)
 
-Coder Tasks is best for cases where the IDE is secondary, such as prototyping or running long-running background jobs. However, tasks run inside full workspaces so developers can [connect via an IDE](../user-guides/workspace-access) to take a task to completion.
+Coder Tasks is best for cases where the IDE is secondary, such as prototyping or running long-running background jobs. However, tasks run inside full workspaces so developers can [connect via an IDE](../user-guides/workspace-access/index.md) to take a task to completion.
 
 You can also interact with Coder Tasks from your IDE. The [Coder extension for VS Code](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote) (and compatible forks like Cursor) enables you to create, monitor, and manage Tasks directly from the IDE, eliminating the need to context-switch to a browser. After logging in, you get access to a dedicated Tasks view in the sidebar that lets you select a template, configure parameters, prompt an agent, and track task status or download logs. Your tasks run in Coder workspaces with access to your repos, credentials, and internal network.
 

docs/install/upgrade.md

@@ -12,7 +12,7 @@ For upgrade recommendations and troubleshooting, see
 ## Reinstall Coder to upgrade
 
 To upgrade your Coder server, reinstall Coder using your original method
-of [install](../install).
+of [install](../install/index.md).
 
 ### Coder install script
 

docs/start/first-template.md

@@ -67,7 +67,7 @@ This starter template lets you connect to your workspace in a few ways:
 - VS Code Desktop: Loads your workspace into
   [VS Code Desktop](https://code.visualstudio.com/Download) installed on your
   local computer.
-- code-server: Opens [browser-based VS Code](../ides/web-ides.md) with your
+- code-server: Opens [browser-based VS Code](../user-guides/workspace-access/web-ides.md) with your
   workspace.
 - Terminal: Opens a browser-based terminal with a shell in the workspace's
   Docker instance.
@@ -77,7 +77,7 @@ This starter template lets you connect to your workspace in a few ways:
 
 > [!TIP]
 > You can edit the template to let developers connect to a workspace in
-> [a few more ways](../ides.md).
+> [a few more ways](../user-guides/workspace-access/index.md).
 
 When you're done, you can stop the workspace. -->
 

docs/tutorials/example-guide.md

@@ -16,7 +16,7 @@ repository.
 
 ## Content
 
-Defer to our [Contributing/Documentation](../contributing/documentation.md) page
+Defer to our [Contributing/Documentation](../about/contributing/documentation.md) page
 for rules on technical writing.
 
 ### Adding Photos