Update Darc documentation to reflect configuration repository workflow

[Copilot]

Description

Recent changes introduced configuration repository support for channel, subscription, and policy management commands. The documentation still described legacy API-based behavior. This PR updates Darc.md to present the configuration repository workflow as the standard approach.

Changes

New Configuration Management Section

Added comprehensive overview section documenting:

• Configuration repository workflow (3-step process: branch creation → file operations → PR)
• Default repository: https://dev.azure.com/dnceng/internal/_git/maestro-configuration
• Common parameters: --configuration-repository, --configuration-branch, --configuration-base-branch, --configuration-file, --no-pr
• Default behavior: automatic PR creation, automatic branch generation based on base branch
• Example workflows focused on standard usage patterns (single command with PR, batching multiple commands)

Updated Command Documentation (10 commands)

Rewrote sections for all commands using ConfigurationManagementCommandLineOptions:

• add-channel, update-channel, delete-channel
• add-default-channel, delete-default-channel, default-channel-status
• add-subscription, update-subscription, subscription-status
• set-repository-policies

Each section now includes:

• Statement that command uses configuration repository workflow
• Parameters with configuration options
• Sample outputs showing only PR creation or branch push (no misleading success messages)
• Cross-references to Configuration Management section

Removed Legacy References

• Removed notes about batchable subscriptions requiring REST API
• Removed notes about repository merge policies being unavailable in darc
• Removed all environment variable/feature flag references

Additional Fixes and Refinements Based on Review Feedback

• Added missing update-channel documentation section
• Fixed broken link in get-channels section
• Updated index with Configuration Management Commands entry
• Corrected terminology: merge policies are set at "repository branch level" (not just "repository level")
• Clarified workflow description: darc creates/updates files directly in branches (no local cloning)
• Removed all misleading success messages from sample outputs (10 occurrences) - commands only create/push branches or open PRs; actual resource creation happens when the PR is merged
• Simplified workflow from 4 steps to 3 steps for accuracy: branch creation (based on base branch) → file operations → PR
• Clarified that new branches are created based on the base branch when not specified
• Updated --configuration-file parameter description to clarify it overrides the default configuration file path
• Removed alternative configuration repository example to keep documentation focused on standard workflow

Example

Before:

### **`add-channel`**
Add a new channel.
**Sample**: darc add-channel --name "Foo"

After:

### **`add-channel`**
Add a new channel.

This command uses the configuration repository workflow. Changes are committed 
to the configuration repository and a pull request is opened by default.

**Parameters:**
- `--name` (required) - Name of the channel to create
- See Configuration Management Commands for additional parameters

**Sample**:
darc add-channel --name "Foo"

A pull request has been opened at: https://dev.azure.com/.../pullrequest/12345

Impact: 267 lines modified (+229, -38) across 10 command sections. Documentation now accurately reflects current behavior with technical details corrected based on review feedback. Workflow description simplified to 3 clear steps that accurately represent what happens: branch is created/updated (based on base branch), files are modified in that branch, and PR is opened. Examples focused on standard usage patterns.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Update darc docs to reflect the new changes</issue_title> <issue_description>## Summary Recent updates introduced support for the new configuration repository across multiple darc commands. These commands can be identified by their Options classes implementing ConfigurationManagementCommandLineOptions. The documentation must be updated so that this new configuration workflow is presented as the only supported behavior (the old API/flag-based behavior will be removed soon).

Task

Update the Darc.md documentation to describe the configuration repository behavior as the default and only method for operations that use ConfigurationManagementCommandLineOptions.

Requirements

1. Update Documentation for All Affected Commands

For all darc operations whose Options derive from ConfigurationManagementCommandLineOptions:

• Rewrite their sections in Darc.md to reflect the new configuration repository workflow.
• Remove references to feature flags or environment-variable–based toggling.
• Present the configuration repository approach as the standard, authoritative behavior.

2. Add a New Section Describing Common Configuration Management Options

Document the shared functionality provided by ConfigurationManagementCommandLineOptions, including:

• How these commands interact with the configuration repository.
• That they open a PR by default unless --no-pr is specified.
• That they operate against the configuration repository unless explicitly overridden. The default configuration repo location: https://dev.azure.com/dnceng/internal/_git/maestro-configuration?path=%2F&version=GBproduction&_a=contents

3. Clarify Default Behavior

Ensure it is clear that:

• The configuration repository is always used unless the user overrides the repo path.
• PR creation is default behavior.

Acceptance Criteria

• Darc.md contains a dedicated section for ConfigurationManagementCommandLineOptions.
• All relevant commands reference this section and describe behavior consistent with the new configuration repo workflow.
• All legacy/flag-based documentation is removed.
• Documentation reads as if the configuration repo workflow was always the default.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes dotnet/arcade-services#5744

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.