π« Toolkit to help you get started with SDD or any other process!
docs: add catalog reference (#4976)
Manfred Riemcd5090e683e6
diff --git a/README.md b/README.mdindex 082d82f07..e06db3ec4 100644--- a/README.md+++ b/README.md@@ -52,8 +52,8 @@ Spec Kit combines ready-to-use processes with composable mechanisms:| Modify an installed workflow without forking it | [Workflow overlay](https://github.github.io/spec-kit/reference/workflows.html#workflow-overlays) || Add reusable executable behavior to workflows | [Workflow step](https://github.github.io/spec-kit/reference/workflows.html#custom-step-packages) || Install a curated setup for a role or team | [Bundle](https://github.github.io/spec-kit/reference/bundles.html) |-| Discover community components | Catalog |-| Host a private catalog of approved components | Catalog |+| Discover community components | [Catalog](https://github.github.io/spec-kit/reference/catalogs.html) |+| Host a private catalog of approved components | [Catalog](https://github.github.io/spec-kit/reference/catalogs.html) || Access private catalogs and component downloads | [Authentication](https://github.github.io/spec-kit/reference/authentication.html) || Work offline or behind a firewall | [Local sources and self-hosted catalogs](https://github.github.io/spec-kit/install/air-gapped.html) || Inspect which layer supplies a command, template, or script | [Artifact inventory](https://github.github.io/spec-kit/reference/artifacts.html) |diff --git a/docs/README.md b/docs/README.mdindex 49936c014..cd5d6db91 100644--- a/docs/README.md+++ b/docs/README.md@@ -32,6 +32,7 @@ To build the documentation locally:- `guides/bugfix.md` - Bug-fixing walkthrough- `guides/assessment.md` - Idea assessment walkthrough- `guides/customization.md` - Choosing and combining customization building blocks+- `reference/catalogs.md` - Catalog discovery, trust, private sources, and precedence- `reference/agentic-*.md` - Detailed process command references- `_site/` - Generated documentation output (ignored by git)diff --git a/docs/community/overview.md b/docs/community/overview.mdindex 8240bde87..6ba99a266 100644--- a/docs/community/overview.md+++ b/docs/community/overview.md@@ -6,6 +6,9 @@ The Spec Kit community builds extensions, presets, bundles, workflow steps, walk> Review community source code before installation and use it at your own> discretion. A catalog listing is not an audit or endorsement.+Learn how discovery-only community sources and approved private sources fit+together in the [catalog reference](../reference/catalogs.md).+## ExtensionsExtensions add new capabilities to Spec Kit β domain-specific commands, external tool integrations, quality gates, and more. Over 130 community extensions are available from 70+ authors, covering everything from accessibility governance to multi-agent orchestration.diff --git a/docs/index.md b/docs/index.mdindex 15dd7f9e3..f3207ae3d 100644--- a/docs/index.md+++ b/docs/index.md@@ -172,7 +172,7 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a</a><a href="reference/overview.md" class="nav-card"><strong>Reference</strong>- <span>Core commands, integrations, extensions, presets, and workflows</span>+ <span>Core commands, catalogs, integrations, extensions, presets, and workflows</span></a><a href="community/overview.md" class="nav-card"><strong>Community</strong>diff --git a/docs/install/air-gapped.md b/docs/install/air-gapped.mdindex b0e20ec0c..fc92013d2 100644--- a/docs/install/air-gapped.md+++ b/docs/install/air-gapped.md@@ -41,6 +41,41 @@ specify init my-project --integration copilot>> **Windows note:** Offline scaffolding requires PowerShell 7+ (`pwsh`), not Windows PowerShell 5.x (`powershell.exe`). Install from <https://aka.ms/powershell>.+## Component catalogs and sources++Built-in integrations and bundled components remain available without network+access. Catalog-based installation of external integration adapters,+extensions, presets, workflows, workflow steps, and bundles needs both the+catalog metadata and the referenced release artifacts. For component types+that support a direct or local source, that installation route does not require+catalog metadata.++For a restricted network that can reach approved internal services, host+reviewed catalogs and artifacts on internal HTTPS endpoints, then register each+component-specific source with its `catalog add` command. For a fully+disconnected network, transfer reviewed component artifacts through your+approved process and install them from their supported direct or local source+instead of relying on an unreachable remote catalog.++External integration adapters are an exception. `specify integration install`+has no direct or local source option: it must resolve the adapter through an+install-allowed integration catalog and download its archive. To add an+external adapter inside an isolated environment, keep both an approved internal+catalog and its adapter archive reachable there, or install the adapter before+disconnecting the target. Transferring the archive alone is not sufficient.++Treat bundles separately: a transferred bundle directory or ZIP supplies the+bundle manifest, not the component payloads it names. Before disconnecting,+install matching non-bundled components separately. Components with an explicit+catalog `source` still require network verification even when already installed,+and workflow step payloads currently resolve only through step catalogs. Review+the [bundle offline limits](../reference/bundles.md#install-a-bundle) before+depending on `specify bundle install --offline`.++See the [Catalogs reference](../reference/catalogs.md) for catalog types, trust+policies, and source precedence. If internal endpoints require credentials,+also configure [Authentication](../reference/authentication.md).+## Git Credential Manager on LinuxIf you're having issues with Git authentication on Linux, you can install Git Credential Manager:diff --git a/docs/reference/catalogs.md b/docs/reference/catalogs.mdnew file mode 100644index 000000000..959fc1e56--- /dev/null+++ b/docs/reference/catalogs.md@@ -0,0 +1,181 @@+# Catalogs++Catalogs are indexes that let Specify discover integrations, extensions,+presets, workflows, workflow step types, and bundles. Spec Kit includes+built-in catalogs, including community catalogs where available, and lets a+project or user add private catalog sources.++A catalog is not one shared registry for every component type. Each component+type has its own catalog schema, command group, configuration, and resolution+stack. An organization that curates several component types normally publishes+one catalog file for each type.++## Discover components++Search uses all active catalogs for that component type:++```bash+specify integration search <query>+specify extension search <query>+specify preset search <query>+specify workflow search <query>+specify workflow step search <query>+specify bundle search <query>+```++Use the corresponding version view to inspect advertised releases:++```bash+specify integration info <id> --versions+specify extension info <id> --versions+specify preset info <id> --versions+specify workflow info <id> --versions+specify workflow step info <id> --versions+specify bundle info <id> --versions+```++Plain `info` output and the details shown by `--versions` vary by component+type. The version view lists current and historical catalog releases and, where+supported, labels the winning source as installable or discovery-only. A+discovery-only release remains non-installable by ID even when it appears in+the version list. Use the component's `catalog list` command to confirm the+active source and install policy instead of relying on plain `info` output.++You can also browse the maintained community lists for+[extensions](../community/extensions.md),+[presets](../community/presets.md), [bundles](../community/bundles.md), and+[workflow step types](../community/workflow-steps.md).++## Inspect and manage catalog sources++List the active catalog stack before installing components from an unfamiliar+project:++| Component type | List active catalogs | Detailed reference |+| --- | --- | --- |+| Integrations | `specify integration catalog list` | [Integrations](integrations.md#catalog-management) |+| Extensions | `specify extension catalog list` | [Extensions](extensions.md#catalog-management) |+| Presets | `specify preset catalog list` | [Presets](presets.md#catalog-management) |+| Workflows | `specify workflow catalog list` | [Workflows](workflows.md#catalog-management) |+| Workflow steps | `specify workflow step catalog list` | [Workflows](workflows.md#catalog-management) |+| Bundles | `specify bundle catalog list` | [Bundles](bundles.md#manage-catalog-sources) |++Each command group also provides `catalog add` and `catalog remove`. Options,+identifiers, install policies, and configuration filenames differ by component+type, so use the linked reference before changing a catalog stack.++Catalog scope and precedence use two models:++- **Integrations, extensions, presets, workflows, and workflow steps** select+ one configuration layer. An environment-variable override replaces+ everything; otherwise a project catalog file replaces the user and built-in+ layers, a user file replaces the built-in layer, and built-in catalogs are+ used only when no higher layer is configured. Within the selected layer,+ entries are ordered by numeric priority. Adding the first project catalog+ therefore removes the built-in sources from the active stack unless you also+ list those sources in the project file.+- **Bundles** merge built-in, user, and project sources by source ID. A+ higher-scope definition replaces a lower-scope source with the same ID, then+ all remaining sources are sorted by numeric priority. A project source does+ not automatically outrank a differently named built-in source.++Among catalogs that load successfully, the higher-priority entry providing an+identifier wins. Some component readers skip ordinary fetch failures and+continue with the remaining sources, so an unreachable higher-priority source+can allow a lower-priority source to resolve the same identifier. Do not treat+source priority as a fail-closed security control.++## Discovery and trust++A catalog listing is not an audit or endorsement. Catalogs can be:++- **Install-allowed**: a source you trust for installation by component ID.+- **Discovery-only**: searchable for evaluation, but blocked from installation+ by ID through that catalog.++Discovery-only policy does not block a separately requested direct-source+installation such as a supported `--from` URL or `--dev` path. Review that+source independently before using the direct-install route.++Community catalogs are discovery surfaces and should remain discovery-only.+Review a component's source and release artifact before using it. To make+reviewed components reusable across a team, copy their vetted entries into a+catalog your organization controls rather than changing an unvetted public+catalog to install-allowed.++Project catalog configuration is also untrusted input. A repository can add or+prioritize catalog sources under `.specify/`, but the presence of that+configuration does not mean its sources or components were approved. Run the+relevant `catalog list` command and inspect every install-allowed source before+installing or running components from an unfamiliar project.++## Host a private catalog++1. Review and approve the entries and release artifacts before registering an+ install-allowed source.+2. Choose the component type and follow its catalog schema or publishing guide.+3. Publish the catalog JSON at an HTTPS URL reachable by the intended users.+4. Add that URL with the component's `catalog add` command.+5. Confirm the resulting source, precedence, and install policy with+ `catalog list`.++The `catalog add` trust default differs by component type:++| Component type | Default when added |+| --- | --- |+| Integrations | Install-allowed |+| Extensions | Discovery-only; requires `--install-allowed` to enable installation |+| Presets | Discovery-only; requires `--install-allowed` to enable installation |+| Workflows | Install-allowed |+| Workflow steps | Install-allowed |+| Bundles | Install-allowed; use `--policy discovery-only` to restrict it |++Because integration, workflow, workflow-step, and bundle additions can permit+installation immediately, do not register an unreviewed source and plan to+approve it later.++Use the component-specific publishing guidance when authoring catalog entries:++| Component type | Publishing guidance |+| --- | --- |+| Integrations | [Integration catalog contributions](https://github.com/github/spec-kit/blob/main/integrations/CONTRIBUTING.md) |+| Extensions | [Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md) |+| Presets | [Preset Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md) |+| Workflows | [Workflow Publishing Guide](https://github.com/github/spec-kit/blob/main/workflows/PUBLISHING.md) |+| Workflow steps | [Community workflow step types](../community/workflow-steps.md) |+| Bundles | [Community bundles](../community/bundles.md) |++For example, a reviewed extension catalog can be registered with:++```bash+specify extension catalog add https://catalog.example.com/extensions.json \+ --name approved-extensions \+ --priority 5 \+ --install-allowed+```++Use separate catalog files and commands for presets, integrations, workflows,+workflow steps, and bundles. Their detailed references document the supported+options and expected entry formats.++## Private and offline environments++If a catalog or its component downloads require credentials, configure+[catalog and download authentication](authentication.md). Authentication is+opt-in and scoped to explicitly configured hosts.++Behind a firewall, host catalogs and artifacts on approved internal HTTPS+endpoints and add those endpoints to the appropriate catalog stacks. In a+fully disconnected environment, transfer the CLI and reviewed component+artifacts through your approved process; built-in assets remain available+without network access. See [Enterprise / Air-Gapped Installation](../install/air-gapped.md)+for installing the CLI offline.++External integration adapters have no direct or local installation route.+Installing one requires both an install-allowed integration catalog and its+referenced archive to remain reachable. See+[Catalog-installed external adapters](integrations.md#catalog-installed-external-adapters).++Catalog metadata alone is not enough for offline installation: every selected+release artifact and any bundle-provided dependency must also be reachable or+transferred into the environment.diff --git a/docs/reference/overview.md b/docs/reference/overview.mdindex b5635fe89..b246bba01 100644--- a/docs/reference/overview.md+++ b/docs/reference/overview.md@@ -21,6 +21,15 @@ Integrations connect Spec Kit to your AI coding agent. Each integration sets up[Integrations reference β](integrations.md)+## Catalogs++Catalogs are priority-ordered indexes for discovering integrations, extensions,+presets, workflows, workflow step types, and bundles. Spec Kit includes+built-in sources and supports private, organization-managed catalogs with+explicit discovery and installation policies.++[Catalogs reference β](catalogs.md)+## ExtensionsExtensions add new capabilities to Spec Kit β domain-specific commands, external tool integrations, quality gates, and more. They are discovered through catalogs and can be installed, updated, enabled, disabled, or removed independently. Multiple extensions can coexist in a single project.diff --git a/docs/toc.yml b/docs/toc.ymlindex 8761b8a49..a374ffd6d 100644--- a/docs/toc.yml+++ b/docs/toc.yml@@ -47,6 +47,8 @@href: reference/mcp.md- name: Integrationshref: reference/integrations.md+ - name: Catalogs+ href: reference/catalogs.md- name: Extensionshref: reference/extensions.md- name: Presets