docs: document Registry v2 repository path limit

docs/en/configure/registry/registry_v2/registry_overview.mdx

@@ -40,7 +40,7 @@ The registry integrates with <Term name="productShort" /> authentication and Kub
 
 | Term | Meaning |
 | --- | --- |
-| Image repository | A namespace-scoped collection of image tags and digests, addressed as `<namespace>/<repository>:<tag>`. |
+| Image repository | A namespace-scoped collection of image tags and digests, addressed as `<namespace>/<repository>:<tag>`. The repository name is a single path segment; nested paths such as `<namespace>/<group>/<repository>:<tag>` are not supported. |
 | ImageStream | <Term name="productShort" /> Image API resource that records tag specifications and tag history for a repository. |
 | Image | Cluster-scoped image metadata for a digest. |
 | ImagePruner | Singleton custom resource that configures scheduled prune jobs. |

docs/en/developer/registry/how_to/common_cli_command.mdx

@@ -10,6 +10,9 @@ i18n:
 
 Use the `ac` CLI for platform login, namespace permission management, and Registry metadata operations. Use a standard OCI client such as `nerdctl` for image transfer operations such as push and pull.
 
+This page documents legacy Registry CLI operations. For Registry v2, use the mode-aware Image and
+ImageStream commands in [Registry v2: Managing Images with ac](../registry_v2/managing_images_with_ac.mdx).
+
 The examples below assume:
 
 - Registry client address: `<REGISTRY_CLIENT_HOSTPORT>`
@@ -50,8 +53,8 @@ If you run `ac` inside a Pod, Job, or CronJob:
 Address usage in this document:
 
 - `<REGISTRY_CLIENT_HOSTPORT>` is the Registry address used by OCI clients such as `nerdctl`.
-- `<REGISTRY_API_URL>` is the Registry API endpoint used by `ac get images` and `ac delete images`.
-- In external access scenarios, `ac` should typically use an explicitly specified `--registry-url` instead of relying on the default in-cluster Registry address.
+- `<REGISTRY_API_URL>` is the legacy Registry API endpoint used by `ac get images` and `ac delete images` in legacy mode.
+- In legacy external access scenarios, `ac` should typically use an explicitly specified `--registry-url` instead of relying on the default in-cluster Registry address.
 
 ## Authenticate to ACP
 
@@ -111,7 +114,7 @@ nerdctl --insecure-registry login <REGISTRY_CLIENT_HOSTPORT> -u <ACP-USERNAME> -
 
 ## List Images
 
-List images from namespaces that the current user is allowed to access:
+List legacy Registry images from namespaces that the current user is allowed to access:
 
 ```bash
 ac get images --registry-url=<REGISTRY_API_URL>
@@ -123,7 +126,7 @@ ac get images -n my-ns --registry-url=<REGISTRY_API_URL>
 ac get images -o yaml --registry-url=<REGISTRY_API_URL>
 ```
 
-When `ac` runs outside the cluster, explicitly specifying `--registry-url` is recommended. Otherwise, the CLI may fall back to the default in-cluster Registry address, which is often unreachable from a local workstation.
+When `ac` runs outside the cluster in legacy mode, explicitly specifying `--registry-url` is recommended. Otherwise, the CLI may fall back to the default in-cluster Registry address, which is often unreachable from a local workstation.
 
 Example:
 
@@ -170,7 +173,7 @@ nerdctl push <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:latest
 
 ## Delete Images
 
-Use `ac delete images` to remove image tags from the Registry:
+Use `ac delete images` to remove image tags from the legacy Registry:
 
 ```bash
 # Preview the deletion result without removing anything

docs/en/developer/registry/registry_v2/accessing_the_registry.mdx

@@ -131,20 +131,28 @@ ac registry login \
   --registry registry.example.com
 ```
 
-To write credentials to a specific Docker-compatible auth file, set `DOCKER_CONFIG` or use `--to`:
+To write credentials to a specific OCI registry auth file, use `--to`:
 
 ```bash
-export DOCKER_CONFIG=/tmp/registry-auth
+mkdir -p /tmp/registry-auth
 
 ac registry login \
   --registry registry.example.com \
-  --to "$DOCKER_CONFIG/config.json"
+  --to /tmp/registry-auth/config.json
 ```
 
 If the registry uses a private CA, configure client trust before push and pull operations. Use `--insecure` only for an HTTP endpoint or a non-production test certificate that the client does not trust.
 
 ## Push and Pull Images
 
+Registry v2 image repositories use exactly two path segments after the registry host:
+
+```text
+<registry-host>/<namespace>/<repository>:<tag>
+```
+
+Repository paths with a third segment after the registry host are not supported. For example, use `registry.example.com/team-a/my-app:v1`, not `registry.example.com/team-a/platform/my-app:v1`. To group related images, use a single repository name such as `platform-my-app`, or use a separate namespace when your namespace model allows it.
+
 Tag and push an image:
 
 ```bash
@@ -191,9 +199,17 @@ Show the Image metadata for a digest:
 ac get imagestreamimages my-app@sha256:<digest> -n team-a -o yaml
 ```
 
-List Registry HTTP image repositories visible to the current user:
+List cluster-scoped Image resources through the current `modern` registry mode:
 
 ```bash
-ac get images --registry-url=https://registry.example.com
-ac get images -n team-a --registry-url=https://registry.example.com
+ac config set-registry-mode modern
+ac get images
+ac get images -o yaml
+```
+
+For namespace-scoped repository views, query ImageStream resources instead of passing a Registry URL override:
+
+```bash
+ac get imagestreams -n team-a
+ac get imagestreamtags my-app:v1 -n team-a -o wide
 ```

docs/en/developer/registry/registry_v2/managing_images_with_ac.mdx

@@ -60,7 +60,7 @@ Check that the Registry `/v2/` endpoint is reachable:
 ac registry info --check
 ```
 
-Write Registry credentials to the default Docker config file:
+Write Registry credentials to the default local credential file:
 
 ```bash
 ac registry login
@@ -69,17 +69,19 @@ ac registry login
 Write credentials to a temporary or CI auth file:
 
 ```bash
-export DOCKER_CONFIG=/tmp/registry-auth
+mkdir -p /tmp/registry-auth
 
 ac registry login \
   --registry registry.example.com \
-  --to "$DOCKER_CONFIG/config.json"
+  --to /tmp/registry-auth/config.json
 ```
 
 Use `--skip-check` when the registry endpoint is not reachable from the current machine but the credential file still needs to be written. Use `--insecure` only when the endpoint is HTTP or uses a certificate that the client does not trust.
 
 ## Manage ImageStreams
 
+Registry v2 maps each image repository to one namespace and one ImageStream name. For `ac` ImageStream references, use `<namespace>/<repository>:<tag>`. For OCI image references, use `<registry-host>/<namespace>/<repository>:<tag>`. Repository paths with an additional path segment, such as `<namespace>/<group>/<repository>:<tag>`, are not supported. Use a single repository name such as `group-repository`, or use a separate namespace when your namespace model allows it.
+
 Create an empty ImageStream:
 
 ```bash
@@ -96,14 +98,14 @@ Create an ImageStreamTag from an external image:
 
 ```bash
 ac create imagestreamtag demo:latest \
-  --from-image=quay.io/example/demo:1.0
+  --from-image=external-registry.example.com/example/demo:1.0
 ```
 
 Import an external image into an ImageStreamTag. Without `--confirm`, the command previews the import. Add `--confirm` to persist the tag:
 
 ```bash
 ac import-image demo:latest \
-  --from=quay.io/example/demo:1.0 \
+  --from=external-registry.example.com/example/demo:1.0 \
   --confirm
 ```
 
@@ -120,7 +122,7 @@ Common import options:
 Tag an external container image into an ImageStreamTag:
 
 ```bash
-ac tag --source=docker quay.io/example/demo:1.0 demo:latest
+ac tag external-registry.example.com/example/demo:1.0 demo:latest
 ```
 
 Copy the current image behind one ImageStreamTag to another:
@@ -238,7 +240,7 @@ ac image info registry.example.com/team-a/demo:latest
 Select one platform from a multi-architecture image:
 
 ```bash
-ac image info docker.io/library/busybox:latest \
+ac image info external-registry.example.com/library/busybox:latest \
   --filter-by-os=linux/arm64
 ```
 
@@ -281,7 +283,7 @@ Add layers or metadata to an image and push the result:
 
 ```bash
 ac image append \
-  --from docker.io/library/busybox:latest \
+  --from external-registry.example.com/library/busybox:latest \
   --to registry.example.com/team-a/busybox:patched \
   layer.tar.gz
 ```
@@ -290,7 +292,7 @@ Preview the append operation:
 
 ```bash
 ac image append \
-  --from docker.io/library/busybox:latest \
+  --from external-registry.example.com/library/busybox:latest \
   --to registry.example.com/team-a/busybox:patched \
   layer.tar.gz \
   --dry-run
@@ -299,7 +301,7 @@ ac image append \
 Extract files from an image without a local container runtime:
 
 ```bash
-ac image extract docker.io/library/busybox:latest \
+ac image extract external-registry.example.com/library/busybox:latest \
   --path /:/tmp/busybox \
   --confirm
 ```