docs: replace deprecated --ai flag with --integration in all documentation

[mnriem]

Summary

Replace all user-facing --ai, --ai-skills, and --ai-commands-dir references in documentation with their modern equivalents:

• --ai <agent> → --integration <agent>
• --ai-skills → --integration-options="--skills"
• --ai-commands-dir <dir> → --integration generic --integration-options="--commands-dir <dir>"

Changes

File	Approx. changes	Notes
README.md	~17	Quick-start examples, usage reference, --ai-skills mentions
docs/installation.md	~8	All uvx one-liner examples, section heading rename
docs/upgrade.md	~11	Every upgrade command example
docs/local-development.md	~5	Dev workflow examples
CONTRIBUTING.md	1	Manual testing example
extensions/EXTENSION-USER-GUIDE.md	1	--ai-skills → --integration-options="--skills"
src/specify_cli/__init__.py	~15	Docstring examples and error message examples

Out of scope (per issue)

• CHANGELOG.md — historical record, left as-is
• Test files — intentionally exercise the deprecated flag path
• CLI flag implementation — backward compatibility preserved

Testing

All 1728 tests pass.

Closes #2358

[Copilot]

Pull request overview

Updates user-facing documentation to use the modern --integration / --integration-options flags instead of deprecated --ai-prefixed flags, reducing first-run deprecation warnings and aligning docs with the current CLI interface.

Changes:

• Replaced --ai / --ai-skills / --ai-commands-dir usage in docs with --integration and --integration-options.
• Updated headings and examples across install/upgrade/dev docs and contributing guide.
• Updated specify init docstring/help examples and related printed example strings.

Show a summary per file

File	Description
README.md	Updates quick-start and detailed examples to use --integration / --integration-options.
docs/installation.md	Renames section and updates uvx install/init examples to --integration.
docs/upgrade.md	Updates upgrade command examples/table entries to use --integration.
docs/local-development.md	Updates local invocation examples to use --integration.
CONTRIBUTING.md	Updates manual testing command example to use --integration.
extensions/EXTENSION-USER-GUIDE.md	Updates skills-mode reference to --integration-options="--skills".
src/specify_cli/init.py	Updates init docstring examples and printed “Example:” guidance strings.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 7/7 changed files
• Comments generated: 4

[Copilot]

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (3)

src/specify_cli/init.py:1033

• The --ai mis-parsed-value check prints an example using --integration, but the error/hint text is specifically about --ai. This mixed messaging can confuse users who just need to add the missing --ai value (or who don’t realize --ai is deprecated). Consider either (a) keeping the example in --ai form, or (b) updating the error/hint to explicitly mention that --ai is deprecated and showing both --integration ... and --ai ... examples.

    if ai_assistant and ai_assistant.startswith("--"):
        console.print(f"[red]Error:[/red] Invalid value for --ai: '{ai_assistant}'")
        console.print("[yellow]Hint:[/yellow] Did you forget to provide a value for --ai?")
        console.print("[yellow]Example:[/yellow] specify init --integration claude --here")
        console.print(f"[yellow]Available agents:[/yellow] {', '.join(AGENT_CONFIG.keys())}")

src/specify_cli/init.py:1040

• This validation branch is triggered for the deprecated --ai-commands-dir flag, but the suggested example uses --integration-options instead. For someone who just forgot to pass a value to --ai-commands-dir, that example doesn’t show the direct fix. Suggest printing an example that uses --ai-commands-dir (and optionally add a second line noting the preferred replacement with --integration generic --integration-options=...).

    if ai_commands_dir and ai_commands_dir.startswith("--"):
        console.print(f"[red]Error:[/red] Invalid value for --ai-commands-dir: '{ai_commands_dir}'")
        console.print("[yellow]Hint:[/yellow] Did you forget to provide a value for --ai-commands-dir?")
        console.print("[yellow]Example:[/yellow] specify init --integration generic --integration-options=\"--commands-dir .myagent/commands/\"")
        raise typer.Exit(1)

docs/installation.md:139

• This section still documents --offline as changing behavior (“use bundled assets instead of downloading from GitHub”), but in the CLI --offline is marked deprecated/no-op and hidden. The docs should be updated to reflect current behavior (bundled assets by default) and avoid instructing users to pass a hidden/deprecated flag; alternatively, keep the note but clarify that --offline is retained only for backward compatibility.

**Step 4: Initialize a project (no network required)**

```bash
# Initialize a project — no GitHub access needed
specify init my-project --integration claude --offline

The --offline flag tells the CLI to use the templates, commands, and scripts bundled inside the wheel instead of downloading from GitHub.

Deprecation notice: Starting with v0.6.0, specify init will use bundled assets by default and the --offline flag will be removed. The GitHub download path will be retired because bundled assets eliminate the need for network access, avoid proxy/firewall issues, and guarantee that templates always match the installed CLI version. No action will be needed — specify init will simply work without network access out of the box.

</details>


- **Files reviewed:** 7/7 changed files
- **Comments generated:** 2

[Copilot]

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (1)

src/specify_cli/init.py:1033

• The error message is specifically about an invalid/missing value for --ai, but the suggested example uses --integration. This can be confusing for users who are trying to fix the --ai invocation; consider showing an example that matches --ai (and optionally a second example for the canonical --integration).

    if ai_assistant and ai_assistant.startswith("--"):
        console.print(f"[red]Error:[/red] Invalid value for --ai: '{ai_assistant}'")
        console.print("[yellow]Hint:[/yellow] Did you forget to provide a value for --ai?")
        console.print("[yellow]Example:[/yellow] specify init --integration claude --here")
        console.print(f"[yellow]Available agents:[/yellow] {', '.join(AGENT_CONFIG.keys())}")

• Files reviewed: 8/8 changed files
• Comments generated: 4

[Copilot]

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 8/8 changed files
• Comments generated: 0 new