docs: improve API introduction page DX (#11749)

<!--
Please inform yourself about the contribution guidelines on submitting a
PR here:
https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr.
Take note of how PR/commit titles should be written and replace the
template texts in the sections below. Do not remove any of the sections.
-->

# Which Problems Are Solved

The `/apis/introduction` page did not give developers clear guidance on
which API version to use. v1 and v2 were presented as equal choices, the
v2 resource list was incomplete, the API path prefix block was
misleading, and several links used inconsistent relative paths.

- No clear recommendation to use v2 for new integrations
- v1 APIs not labelled as legacy
- "APIs v2" section only listed 3 of 15 available v2 services
- Path prefix block only listed 5 of 15 v2 gRPC service paths, with no
distinction between REST and gRPC/Connect access patterns
- `/ui/` path listed as a single entry — the Management Console
(`/ui/console/`) and hosted Login UI (`/ui/login/`) were not
distinguished
- Relative links (`../guides/...`, `./assets/assets`) inconsistent with
the rest of the page
- Auth disclaimer paragraph was confusing; "Custom" section heading was
unclear

# How the Problems Are Solved

- **v2-first framing**: Added a clear directive — "Use the v2 APIs for
all new integrations" — and renamed the old section to "Legacy v1 APIs"
- **Complete v2 resource list**: All 15 v2 services now listed with
one-line descriptions (User, Session, Org, Instance, Project,
Application, IDP, Group, Settings, Feature, Authorization, Action,
WebKey, OIDC, SAML)
- **Full path prefix list**: All 15 v2 gRPC service paths listed; split
into `# REST (HTTP/JSON transcoding): /v2/` and `# gRPC + Connect
protocol (binary or JSON via connectRPC):`
- **`/ui/` paths clarified**: Split into `/ui/console/` (Management
Console) and `/ui/login/` (Hosted Login UI) with inline comments
- **Fixed relative links**: `../guides/...` → `/guides/...`;
`./assets/assets` → `/apis/assets/assets`
- **Section copy improvements**: Auth disclaimer removed; "Custom"
renamed to "Session-based and custom login" with clear bullet list; v1
API card descriptions updated with v2 pointers; Assets card, System card
title fix
- **Client libraries section**: Replaced noisy "API definitions" section
with cleaner "Client libraries & schemas"

# Additional Context

All changes are in `apps/docs/content/apis/introduction.mdx`,
`apps/docs/content/apis/v2.mdx`, and
`apps/docs/content/apis/migration_v1_to_v2.mdx`.

Co-authored-by: Copilot <[email protected]>

apps/docs/components/docusaurus/doc-card-list.tsx

@@ -13,18 +13,5 @@ export default function DocCardList({ items }: { items?: any[] }) {
     );
   }
 
-  // If no items, it's likely an auto-generated list for the current sidebar category.
-  // Fumadocs doesn't have a direct equivalent to "current sidebar category items" in a component easily accessible here without context.
-  // For now, we'll render a placeholder or nothing to avoid build errors.
-  // In a real migration, we'd use `useTreeContext` or similar if available, or rely on Fumadocs' index page generation.
-  return (
-    <div className="admonition admonition-info alert alert--info">
-      <div className="admonition-heading">
-        <h5>DocCardList Placeholder</h5>
-      </div>
-      <div className="admonition-content">
-        <p>Auto-generated card lists are not yet fully supported in the migration.</p>
-      </div>
-    </div>
-  );
+  return null;
 }