[mnriem]

Description

Consolidates extension documentation under docs/extensions/, with dedicated CLI and catalog references, and removes the old docs/reference/extensions.md page. Updates navigation and inbound links to the canonical pages.

Aligns manifest validation, configuration loading, registry formats, command lifecycle, hooks, runtime events, catalog behavior, and publishing guidance with the current implementation. Corrects examples and support destinations. The community extension listing remains in docs/community/extensions.md.

This is documentation-only; runtime behavior and submission automation are unchanged.

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest
• Tested with a sample project (if applicable)

Validation:

• uv run specify --help — passed.
• .venv/bin/python -m pytest tests/test_extensions.py tests/specify_cli/extensions tests/extensions/bug/test_bug_hooks.py tests/test_catalog_trust_docs.py tests/specify_cli/bundles/test_primitives.py::test_extension_pin_selects_historical_catalog_release -q — 765 passed.
• npx --no-install markdownlint-cli2 'docs/extensions/*.md' — passed, no issues.
• docfx docs/docfx.json — passed with three pre-existing warnings.

The full test suite and a coding-agent sample-project process were not run for this documentation-only change.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: Authored with GitHub Copilot App using GPT-6.1 Sol (gpt-6.1-sol), in autonomous agent mode with runtime-default reasoning settings and human-directed scope. AI assistance covered documentation consolidation, source comparison, documentation corrections, validation, and PR preparation. No runtime code was changed.

[Copilot]

🟡 Changes recommended

An active documentation issue remains because the change unconditionally describes hooks and events as disabled despite refresh failures potentially leaving a stale runtime hook active.

1 open issue

• Qualify event disablement as best-effort · New

What changed in this PR

This documentation-only pull request consolidates extension guidance under docs/extensions/, removes the legacy extension reference page, and updates navigation and inbound links to reflect current implementation behavior.

Changes:

• Adds dedicated CLI, catalog, API, development, overview, and publishing documentation.
• Updates manifest, configuration, catalog, lifecycle, hook, runtime-event, and publishing guidance.
• Repoints repository and documentation links to the new canonical pages.

This pull request requires changes.

File	Description
README.md	Updates extension links to the new documentation pages.
docs/​upgrade.md	Points extension update guidance to the CLI reference.
docs/​toc.yml	Adds extension documentation navigation and removes the legacy entry.
docs/​reference/​overview.md	Links to the canonical extension CLI reference.
docs/​reference/​extensions.md	Removes the superseded consolidated extension reference.
docs/​reference/​catalogs.md	Links catalog guidance to the new canonical page.
docs/​README.md	Documents the reorganized extension documentation structure.
docs/​index.md	Updates the main Extensions landing-page link.
docs/​guides/​customization.md	Updates extension management and configuration links.
docs/​extensions/​publishing.md	Updates community publishing requirements and submission guidance.
docs/​extensions/​overview.md	Documents current installation, configuration, lifecycle, hook, event, and trust behavior.
docs/​extensions/​developing.md	Aligns authoring guidance with current manifest, hook, event, script, and configuration contracts.
docs/​extensions/​cli.md	Adds the dedicated extension command reference.
docs/​extensions/​catalogs.md	Adds catalog trust, resolution, configuration, and release-schema guidance.
docs/​extensions/​api.md	Updates manifest, registry, configuration, hook, and runtime-event API documentation.

_{Review effort: Lite (auto)}

[mnriem]

Updated the CLI reference and overview in df04e30 to distinguish persisted declarative hook disablement from best-effort native event refresh. Both pages now warn that a failed refresh can leave a stale native hook active and identify specify integration upgrade <key> as the retry path. Markdown lint and the documentation build passed; the build retains three pre-existing warnings. No runtime behavior changed.

Posted on behalf of mnriem by GitHub Copilot App using GPT-6.1 Sol (gpt-6.1-sol), autonomous mode with runtime-default reasoning settings; AI assistance covered the documentation correction, validation, commit, and this review-round summary.

[Copilot]

🔵 Needs a closer look

The documentation contains an active nit because its final sentence overstates CLI verification and must be scoped to versioned catalog installs or corrected to reflect actual behavior.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Scope manifest verification claim to --version installs

docs/​extensions/​cli.md:49

The final sentence overstates the verification performed by the CLI. command_add passes expected_id/expected_version to install_from_zip only for --version catalog installs; unqualified catalog installs and direct --from installs validate the manifest but do not compare its ID/version with an expected catalog value. Please scope this claim to --version installs (or document the actual behavior).

1 resolved since last review

• Qualify event disablement as best-effort

_{Review effort: Lite (auto)}

[mnriem]

Updated the CLI reference in 111f1d6 to scope expected manifest ID/version comparisons to --version catalog installs. It now explicitly distinguishes ordinary catalog and direct URL installs, which validate the manifest without comparing it with expected catalog values. Markdown lint and whitespace checks passed. No runtime behavior changed.

Posted on behalf of mnriem by GitHub Copilot App using GPT-6.1 Sol (gpt-6.1-sol), autonomous mode with runtime-default reasoning settings; AI assistance covered source verification, the documentation correction, validation, commit, and this review-round summary.

[Copilot]

🟢 Approval recommended

The documentation-only changes align the extension guides, navigation, and links with the current implementation, with review feedback limited to non-blocking clarification nits.

No open issues 🎉

_{Review effort: Lite (auto)}