docs: add ADC user documentation (#524)

* docs draft

* docs: restructure ADC documentation (#530)

* docs: limit root README changes

* docs: address ADC review comments

* docs: fix ADC built-in variable example

---------

Co-authored-by: Traky Deng <trakydeng@gmail.com>

Author: bzp2010

README.md

@@ -100,6 +100,10 @@ The `lint` command verifies the provided ADC configuration file locally.
 adc lint -f adc.yaml
 ```
 
+## Documentation
+
+See the [`docs/`](docs/README.md) folder for the CLI command reference, configuration file reference, and a full ADC workflow guide.
+
 ## Development
 
 To build ADC from source, [install Nx](https://nx.dev/getting-started/installation) and run:

docs/README.md

@@ -0,0 +1,25 @@
+# ADC Documentation
+
+API Declarative CLI (ADC) manages Apache APISIX and API7 Enterprise configuration from local YAML or JSON files. Use it to export existing gateway configuration, review drift, validate proposed changes, and apply the desired state through the gateway Admin API.
+
+Start with the workflow guide if you are setting up ADC for the first time. Use the reference pages when you need exact command flags, configuration fields, or OpenAPI conversion behavior.
+
+## Get Started
+
+- [Use ADC for Declarative Configuration](./guides/workflow.md): configure a backend, write an `adc.yaml` file, lint it, preview changes, sync it, and export backups.
+- [Resource IDs](./guides/resource-ids.md): understand how ADC matches local resources to remote resources, especially before adopting resources that were created outside ADC.
+- [Label Selector](./guides/label-selector.md): split ownership by labels so multiple teams or pipelines can manage one backend safely.
+
+## Reference
+
+- [CLI Command Reference](./reference/cli.md): commands, flags, backend options, and examples.
+- [Configuration Reference](./reference/configuration.md): ADC configuration file structure, variables, resource fields, and links to the generated schema.
+- [OpenAPI Converter Reference](./reference/openapi-converter.md): `adc convert openapi`, supported `x-adc-*` extensions, merge rules, and examples.
+
+## Component Notes
+
+These files describe implementation-specific behavior for ADC backends and converters:
+
+- [Apache APISIX backend](../libs/backend-apisix/README.md)
+- [API7 Enterprise backend](../libs/backend-api7/README.md)
+- [OpenAPI converter](../libs/converter-openapi/README.md)

docs/guides/label-selector.md

@@ -0,0 +1,111 @@
+# Label Selector
+
+`--label-selector` scopes ADC operations to resources with matching labels. Use it when multiple teams, applications, or CI pipelines manage separate parts of the same backend.
+
+Without a selector, `adc sync` reconciles all resources in the command scope. If team A and team B sync separate files to the same backend without partitioning, one team can accidentally delete the other team's resources. A selector prevents that by making each run see only its own labeled resources.
+
+## Basic Usage
+
+```bash
+adc sync -f team-a.yaml --label-selector team=a
+```
+
+You can provide multiple labels in one flag or repeat the flag:
+
+```bash
+adc sync -f catalog.yaml --label-selector team=catalog,env=prod
+adc sync -f catalog.yaml --label-selector team=catalog --label-selector env=prod
+```
+
+Matching uses exact string equality. Multiple labels are combined with AND, so a resource must match every key-value pair to be included.
+
+ADC does not support wildcards, OR expressions, or key-exists selectors. There is no `ADC_*` environment variable for label selectors; pass them as command-line flags.
+
+## How Remote Filtering Works
+
+For `dump`, and for the remote side of `diff` and `sync`, ADC filters remote resources by label.
+
+Remote filtering applies to top-level resource collections that carry labels, such as:
+
+- `services`
+- `consumers`
+- `consumer_groups`
+- `ssls`
+- other label-bearing top-level resource collections supported by the backend
+
+Remote filtering does not apply to `global_rules` or `plugin_metadata`. These resources are keyed by plugin name and are treated as global configuration.
+
+Filtering does not independently select nested resources. If a service matches the selector, its routes and stream routes are included with the service. If a consumer group matches the selector, its nested consumers are included with the group.
+
+For API7 Enterprise, ADC passes label filters to the Admin API so the backend can filter matching top-level resources. For Apache APISIX, ADC fetches the remote configuration and applies the same label filtering client-side.
+
+## How Local Label Injection Works
+
+ADC also applies the selector to the local file. It merges the selector labels into each local top-level resource and selected nested resources. For `diff` and `sync`, this happens before ADC compares the local file with the backend. For `validate`, this happens before ADC sends the local resources for backend validation.
+
+For example, this command:
+
+```bash
+adc sync -f catalog.yaml --label-selector team=catalog
+```
+
+turns a local service like this:
+
+```yaml
+services:
+  - name: catalog
+    routes:
+      - name: list-products
+        uris:
+          - /products
+```
+
+into an in-memory configuration equivalent to:
+
+```yaml
+services:
+  - name: catalog
+    labels:
+      team: catalog
+    routes:
+      - name: list-products
+        labels:
+          team: catalog
+        uris:
+          - /products
+```
+
+If the file already has the same label key, the selector value wins.
+
+This behavior keeps future runs stable. Resources created under a selector remain visible to that selector, and nested resources do not produce repeated diffs just because the backend copy has labels added by an earlier sync.
+
+## Share One Backend Across Teams
+
+Team A and team B can manage separate files against the same backend:
+
+```bash
+# Team A
+adc sync -f team-a.yaml --label-selector team=a
+
+# Team B
+adc sync -f team-b.yaml --label-selector team=b
+```
+
+Team A sees and reconciles only resources labeled `team=a`. Team B sees and reconciles only resources labeled `team=b`.
+
+To inspect one partition:
+
+```bash
+adc dump -o team-a.yaml --label-selector team=a
+```
+
+## Important Limits
+
+- Do not use label selectors to split ownership of routes inside one shared service. A service is the top-level unit for filtering, so its nested routes move with it.
+- Use `--gateway-group` for API7 Enterprise gateway group isolation. Use `--label-selector` when teams share a gateway group or when the backend is Apache APISIX.
+- Be careful with `global_rules` and `plugin_metadata`. They are global and are not filtered by label selector.
+
+## Related
+
+- [Resource IDs](./resource-ids.md)
+- [CLI Command Reference](../reference/cli.md#common-backend-options)

docs/guides/resource-ids.md

@@ -0,0 +1,69 @@
+# Resource IDs
+
+ADC matches local resources to remote resources by resource ID. Names are used to generate IDs only when an explicit `id` is not present in the local configuration.
+
+This matters most when adopting resources that already exist on the backend. A resource created through a UI or Admin API may have a server-generated ID that does not match the ID ADC would derive from its name. If ADC cannot match the IDs, it treats the local resource and remote resource as different resources.
+
+## Why IDs Matter
+
+`adc sync` is a reconciliation operation. For each resource in scope, ADC compares the local desired state with the remote state and computes create, update, and delete events.
+
+If an existing remote resource has ID `abc123`, but the local file describes a similar resource with generated ID `def456`, ADC does not treat that as an in-place update. It sees:
+
+- one remote resource to delete
+- one local resource to create
+
+Depending on the resource, that replacement can cause traffic disruption, break references that use the old ID, or create unnecessary audit history.
+
+## Generated IDs
+
+When no explicit `id` is set, ADC derives IDs deterministically.
+
+| Resource type       | Generated ID                                    |
+| ------------------- | ----------------------------------------------- |
+| Consumer            | `username`                                      |
+| Global rule         | Plugin name                                     |
+| Plugin metadata     | Plugin name                                     |
+| Service             | `sha1(name)`                                    |
+| SSL                 | `sha1(snis.join(','))`                          |
+| Upstream            | `sha1("<service-name>.<upstream-name>")`        |
+| Route               | `sha1("<service-name>.<route-name>")`           |
+| Stream route        | `sha1("<service-name>.<stream-route-name>")`    |
+| Consumer credential | `sha1("<consumer-username>.<credential-name>")` |
+
+For resources that ADC created and continues to manage, you normally do not need to write IDs by hand. ADC will generate the same ID from the same names on every run.
+
+## Rename Behavior
+
+If a resource uses a generated ID, renaming it changes the generated ID. ADC will treat that as deleting the old resource and creating a new one.
+
+To rename a resource without changing its backend ID:
+
+1. Export the resource with explicit IDs.
+2. Keep the `id` field in the file.
+3. Change the display name or resource name while preserving the `id`.
+4. Run `adc diff` and confirm the change is an update, not a delete and create.
+
+## Adopt Existing Resources
+
+Before pointing ADC at resources that were created outside ADC, export the current backend state with IDs:
+
+```bash
+adc dump --with-id -o adc.yaml
+```
+
+Then confirm that ADC sees no changes:
+
+```bash
+adc diff -f adc.yaml
+```
+
+If the diff is empty, commit the file and use it as the starting point for ADC-managed configuration.
+
+Keep the exported `id` fields. Removing them later can cause ADC to fall back to generated IDs and replace the resources on the next sync.
+
+## Related
+
+- [Use ADC for Declarative Configuration](./workflow.md)
+- [CLI Command Reference](../reference/cli.md#adc-dump)
+- [Configuration Reference](../reference/configuration.md)