sphinx-autodoc-argparse(docs[domain]): document :argparse:* roles and indices

why: The argparse domain is live (E1-E5) and sits in Tier 2 (E6),
but the package page has no user-facing documentation on how to
use the new xref roles or the two auto-generated indices.  Add a
"Cross-reference roles" section covering the full role vocabulary,
the target-syntax rules (whitespace-joined vs bare), and the
intersphinx-compat contract — so readers know `:argparse:option:`
is now the idiomatic form without losing `:option:` access for
intersphinx consumers.
what:
- Add a "Cross-reference roles" section to
  docs/packages/sphinx-autodoc-argparse.md after "Inline roles"
  with:
    * A four-row table listing :argparse:program: /
      :argparse:option: / :argparse:subcommand: /
      :argparse:positional: with concrete example targets.
    * A short paragraph on target-syntax rules (whitespace-join
      splits into a (program, name) tuple key; bare form resolves
      when there's one match).
    * "Auto-generated indices" subsection naming
      argparse-programsindex and argparse-optionsindex with
      :ref: link examples.
    * "Intersphinx compatibility" note clarifying that
      :option: / std:cmdoption continues to resolve and appear in
      objects.inv for external consumers.

Author: tony

docs/packages/sphinx-autodoc-argparse.md

@@ -51,6 +51,43 @@ The exemplar layer also registers live inline roles for CLI prose:
 {cli-command}`myapp`, {cli-option}`--verbose`, {cli-choice}`json`,
 {cli-metavar}`DIR`, and {cli-default}`text`.
 
+## Cross-reference roles
+
+Every `.. argparse::` block populates a dedicated `argparse` domain
+alongside the existing `std:cmdoption` entries.  Use these roles to
+link to programs, options, subcommands, and positional arguments
+declared anywhere in the project:
+
+| Role | Resolves to | Example |
+|------|-------------|---------|
+| `:argparse:program:` | A top-level program | `` :argparse:program:`myapp` `` |
+| `:argparse:option:` | An optional flag, scoped by program | `` :argparse:option:`myapp --verbose` `` or `` :argparse:option:`myapp sync --force` `` |
+| `:argparse:subcommand:` | A subcommand under a parent program | `` :argparse:subcommand:`myapp sync` `` |
+| `:argparse:positional:` | A positional argument, scoped by program | `` :argparse:positional:`myapp FILE` `` |
+
+Whitespace-joined targets (`myapp sync --force`) are split on the final
+space to match the stored `(program, name)` tuple.  Bare forms
+(`--verbose`) also resolve when only one registration matches, though
+the fully-qualified form is preferred for multi-program sites.
+
+### Auto-generated indices
+
+Two domain indices are built into every project that loads the
+extension:
+
+- `argparse-programsindex` — alphabetised list of every registered
+  program; link via `` :ref:`argparse-programsindex` ``.
+- `argparse-optionsindex` — options grouped by program, alphabetised
+  within each group; link via `` :ref:`argparse-optionsindex` ``.
+
+### Intersphinx compatibility
+
+The classic `:option:` / `std:cmdoption` emission is preserved — both
+roles resolve and both appear in `objects.inv`.  Downstream consumers
+linking via intersphinx continue to work; new authoring inside
+projects using this extension can prefer the `:argparse:*` namespace
+for program-scoped clarity.
+
 ## Configuration values
 
 ### Base extension