# CAT Agents & Workflows Gallery
A community gallery for **Copilot Studio apps, agents, and workflows**. Agent and
workflow entries come from exploded Power Platform solutions; managed app entries
come from portable source for a new platform-managed deployment. Visitors can
explore architecture, source inventory, and setup before installing.
The site uses Astro, Tailwind CSS, React Flow, and static GitHub Pages deployment.
## Features
- Searchable gallery of complete submissions, filterable by apps, agents, or workflows,
category, tag, contributor, and component types. The **Contains** filter requires
every selected type: for example, MCP servers and Skills must both be present
in the solution.
- Separate Microsoft and community browsing sections that stay in place during
search and filtering, with their own matches and empty states. Homepage sorting
applies to community solutions; the dedicated
Microsoft listing has its own sort control. Both pages share the same search
and filter controls, and their navigation links carry the active filters and
sort order. Filters stay selected even when they have no Microsoft matches;
counts and results reflect the gallery being viewed. The homepage's
**View more** link sits beside the Microsoft solution count
and appears only when the responsive preview leaves additional cards hidden.
- One entry per solution, with Overview and Files tabs. Agents and Workflows
tabs appear only when those assets are present.
- Agent component tables listing each agent's tools, MCP servers, skills, and
connected agents.
- An informational workflow table listing each workflow's trigger, steps,
connector services, and agent calls, including inline agents.
It shares the Agents roster's icon-led rows and typography, with step counts
beneath workflow names. There is no second canvas or preview selector.
On phones, rows stack into compact summaries.
- Every submission containing workflows must set `previewWorkflow` in
`metadata.json` to a workflow ID or unique display name, even with only one
workflow. CI rejects missing or invalid selections; there is no automatic
default. Agent-only submissions omit this field.
- The hero renders each export's saved designer graph, preserving loop containers
and parent-relative step positions. Zoom, full-screen viewing, and node details
remain available, with agent steps showing their components on hover or select.
Full-screen transitions automatically refit the graph to the resized canvas.
- Workflow nodes keep their submitted titles and separately identify connector
services and trigger types (such as HTTP, email, or manual) from export metadata.
Titles and metadata wrap without truncation. Missing types are explained once
per workflow and in node details, never guessed from the step title.
- Deterministic downloadable ZIP rebuilt from the submitted exploded solution.
- Compact downloads near the top of narrow solution pages, with a visible trust
checkbox and support disclaimer. The ZIP stays locked until the import warning
is acknowledged. Microsoft-provided samples and community examples have distinct
acknowledgement text; package metadata is available in the **Files** tab.
- Contributor directory, individual contributor profiles, and JSON catalog endpoint.
- Pull-request validation for metadata, solution structure, graph availability,
unsafe filesystem entries, and generated output.
- Managed app detail pages with connector/schema prerequisites, app source ZIPs,
and visible macOS Bash / Windows PowerShell setup commands. Two shared installers
offer missing prerequisites with consent, make the first-party CLI available
through npm, then sequence native creation/connection prompts,
dependency installation, pack, Git save/push, hosted build, and preview.
The CLI owns authentication and platform behavior; setup never publishes live.
- A [Team Ideas Board](submissions/team-ideas-board/) SharePoint starter for learning
source customization and contribution. See [the full managed app guide](docs/managed-apps.md).
## Local development
```bash
npm install
npm run import:submissions
npm run dev
```
The site is configured for GitHub Pages at:
```text
http://localhost:4321/copilot-studio-gallery/
```
Useful commands:
```bash
npm test
npm run seed:demos
npm run check:submissions
npm run import:submissions
npm run astro -- check
npm run build
npm run preview
```
`npm run seed:demos` recreates the 12 deterministic demo submissions used to
develop and preview the gallery's category-led discovery experience.
The scoped npm override for `@tailwindcss/typography` keeps its
`postcss-selector-parser` dependency on patched 6.x releases. Remove it once
Typography no longer pins the vulnerable `6.0.10` version.
### Solution discussions
Solution detail pages include a **Rate & discuss** section, using the same
GitHub Discussions / giscus approach as the CAT Skills Gallery. Each solution
maps to a discussion by its stable submission slug, so changing its display name
does not lose its conversation. Visitors sign in with GitHub to comment or react.
Discussions must be enabled and [giscus](https://github.com/apps/giscus) must be
installed for `microsoft/copilot-studio-gallery`. The shared public repository
and category identifiers live in `src/lib/discussion-config.json`; they are not
credentials. The **Announcements** category lets giscus create threads without
opening thread creation to all visitors. Comments and reactions are public on
GitHub. The thread is created on the first comment or reaction, not on page view.
The embed uses our custom styles in `public/giscus/`, with light and dark
palettes matching the gallery and synchronized with its theme toggle. Production
theme URLs include the GitHub Pages base path. Local development sends the same
CSS as a self-contained data URL through giscus's theme configuration after the
widget is ready. This avoids browsers blocking an HTTPS iframe's stylesheet
request to an HTTP localhost server; no public upload or CORS relaxation is
needed. Local commenting is **live**, not simulated. Backlinks always point to
the deployed gallery rather than localhost. Live reaction counts are not yet
used for gallery sorting.
The **Notify sample submitters** workflow runs on new discussion comments after
the workflow is merged into `main`. It resolves the discussion slug against
trusted generated solution metadata, then mentions all credited `authors[].github`
handles on the first community comment. It ignores bots, author self-comments,
unpublished demo samples, and unrelated categories or discussion titles. A
bot-authored marker and per-discussion concurrency prevent duplicate notifications,
including on reruns and when several comments arrive together. Author comments
do not consume the notification: the first later visitor comment still triggers it.
Samples without credited GitHub handles are logged and skipped. No PR submitter
or merger is guessed from repository history, and no new token secret is needed:
the workflow uses `GITHUB_TOKEN` with `contents: read` and `discussions: write`.
## Submit a sample
Share one complete sample under `submissions/<slug>/`:
| Sample | Source format | Contribution path |
| --- | --- | --- |
| Managed app | Portable source in `app/`, required README, and `submissionType: "managed-app"` | [Prepare an app](CONTRIBUTING.md#contributing-a-managed-app) with the native CLI and `npm run prepare:app` |
| Agents and/or workflows | Complete exploded Power Platform export in `solution/`, not a ZIP | [Prepare a solution](CONTRIBUTING.md#contributing-a-solution) |
Both use gallery metadata, shared validation, a fresh-environment test for their
format, and a pull request. Start with the
[contribution guide](CONTRIBUTING.md) for the end-to-end process.
## Deployment
Pull requests run validation, tests, type checks, and a production build.
Merges to `main` deploy the static site to:
<https://microsoft.github.io/copilot-studio-gallery/>
Production builds load Microsoft Clarity project `z2dufgqwq5` on every page
through the shared layout. Local development does not load Clarity.
### Browser dependency notices
The client build automatically generates `dist/third-party-notices.txt` from
bundled dependencies, including dependency styles. The footer links to this file
under the configured site base. The file includes installed package versions and
the full license and accompanying notice texts; it is deployed with the site,
not added to submitted solution or managed-app downloads.
Generation uses Vite's license inventory and preserves additional license,
NOTICE, copyright, and author files from the installed packages. A missing or
empty license file fails the build with the package name: check the upstream
package's published license files and resolve the packaging issue before
releasing. Do not substitute an SPDX label or silently skip the package.
In development, the same URL generates notices through an in-memory browser
build of the installed React/graph entries and discovered client dependencies.
This development inventory may be broader than the optimized production bundle;
it never relies on an earlier `dist/` build. Production inventories exclude
dependencies used only by the importer or build tooling. Notice generation does
not install or execute submitted app dependencies and does not replace required
license review or registration.
## License
[MIT](LICENSE)