Showcall · breman27 · Jul 11, 2026 · Jul 11, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -11,7 +11,7 @@ name: Release
 #   3. On npmjs.com, each package -> Settings -> Trusted Publishing: add this
 #      repo (org `Showcall`, repo `agent-catalog`, workflow `release.yml`).
 #
-# After that, `git tag v0.1.0 && git push origin v0.1.0` publishes both
+# After that, push a matching `vX.Y.Z` tag to publish both
 # packages with no token. Publish uses the npm CLI, not yarn: yarn's publish
 # does not perform the npm OIDC exchange.
 #
@@ -61,8 +61,8 @@ jobs:
       # Publish with the npm CLI (not `yarn npm publish`) so the OIDC exchange
       # runs. No NODE_AUTH_TOKEN: npm uses the workflow's id-token. Provenance
       # is generated automatically; --provenance makes it explicit.
-      # Each step skips a version that is already on npm, so re-runs and the
-      # retroactive v0.1.0 tag (bootstrapped manually) don't hard-fail.
+      # Each step skips a version that is already on npm, so re-runs and tags
+      # for already-published versions do not hard-fail.
       - name: Publish backend module
         working-directory: plugins/catalog-backend-module-agent-catalog
         run: |

diff --git a/README.md b/README.md
@@ -34,13 +34,16 @@ questions for services. This plugin makes it answer them for agents.
   deprecated models, over-privileged tool access — all standard catalog
   queries ([governance.md](docs/governance.md)).
 - **A fleet view.** The `/agents` page: every agent across all sources with
-  owner, runtime, reachability, and traction in one sortable table — plus an
-  Agent card on each entity page.
+  owner, runtime, reachability, traction, health findings, and configurable
+  columns in one sortable table — plus an Agent card on each entity page.
+- **Opt-in shadow discovery.** The audit sweep probes unlabeled Services for
+  valid A2A cards and surfaces agents nobody registered, with explicit
+  suppression and bounded probing controls.
 
 ## Compatibility
 
-This is a **technical preview** (v0.1.x). While on the `0.x` line, config keys
-and package APIs may still change.
+This is a **technical preview**. While on the `0.x` line, config keys and
+package APIs may still change.
 
 | Requirement | Supported |
 |---|---|
@@ -244,10 +247,10 @@ New to agents, A2A, or MCP? Start with the primer.
   successful sync; transient cluster failures keep the last successful
   per-cluster snapshot so outages do not look like mass deletions
   ([ADR 0003](docs/adr/0003-full-mutation-per-refresh.md)).
-- **Frontend v1 shipped**: an `/agents` fleet page (owner, runtime,
-  discovery, reachable, last-active, requests) and an Agent card on every
-  agent's entity page. Future: card/skill viewer, fleet filters, the
-  gateway Resource page.
+- **Frontend v1 shipped**: an `/agents` fleet page with health findings,
+  click-to-filter triage, shadow markers, and configurable columns, plus an
+  Agent card on every agent's entity page. Future: card/skill viewer, event
+  timeline, and richer usage scorecards.
 - **Scaffolder PR flow assumes GitHub**; swap the publish action for
   GitLab etc. as needed.
 

diff --git a/docs/adr/0008-gateway-usage.md b/docs/adr/0008-gateway-usage.md
@@ -4,8 +4,9 @@
 - Date: 2026-07-04
 
 > **Implementation notes** (verified against a live LiteLLM proxy):
-> `/global/spend/report` turned out to be enterprise-gated; the
-> implementation reads the OSS `/user/daily/activity` endpoint instead,
+> `/global/spend/report` was not available in the supported LiteLLM
+> deployment; the implementation reads the OSS
+> `/user/daily/activity` endpoint instead,
 > whose `breakdown.api_keys` carries `key_alias` + `team_id` — the whole
 > matching ladder in one call (paginated via `has_more`; `/team/list`
 > resolves team aliases, best-effort). Annotations shipped as

diff --git a/docs/concepts.md b/docs/concepts.md
@@ -81,10 +81,10 @@ flaw, it's what a registry *is*. The catalog's audit sweep
 ([ADR 0007](adr/0007-audit-sweep.md)) exists precisely for that gap, and
 `reachable: false` is a fact no registry entry carries.
 
-The two compose rather than compete: an org's registries are natural
+The two compose rather than compete: an organization's registries are natural
 **sources** for this catalog ([roadmap](roadmap.md), Tier C) — as
-enterprises accumulate one registry per cloud, the org-wide observation
-layer that reads *across* them is exactly the role a portal catalog plays.
+organizations accumulate one registry per cloud, the org-wide observation
+layer that reads *across* them is exactly the role a catalog plays.
 
 ## Ownership, in one paragraph
 

diff --git a/docs/governance.md b/docs/governance.md
@@ -10,7 +10,7 @@ third. Conflating them is how governance products overpromise — so we won't.
 |---|---|---|
 | **Version / drift sprawl** | Ten slightly-different copies of an agent because people tweak configs in place | **Largely solved.** One declared spec per environment in git; Argo `selfHeal` reverts out-of-band changes. The cluster is forced to match the repo. |
 | **Count sprawl** | Agent #40 gets merged and nobody remembers #12 | **Converted, not prevented.** Every agent that exists is in the catalog with an owner, model, and tool dependencies. Proliferation becomes a *queryable list you can prune* — see scorecards below. Pruning remains an org discipline. |
-| **Shadow / runtime sprawl** | Agents on laptops, in Lambdas, embedded in apps; sub-agents spawned at runtime | **Partially covered.** Any on-cluster agent — whatever framework — is one Service label away from being cataloged ([ADR 0006](adr/0006-a2a-label-discovery.md)), so "we don't run kagent" is no longer an excuse. What remains dark: *unlabeled* on-cluster agents (heuristic discovery + the audit sweep on the [roadmap](roadmap.md) hunt these), and anything off-cluster or spawned at runtime — for those, an org **LLM gateway** is the honest instrument: usage that can't be attributed to any cataloged agent is itself the shadow-agent signal. |
+| **Shadow / runtime sprawl** | Agents on laptops, in Lambdas, embedded in apps; sub-agents spawned at runtime | **Partially covered.** Any on-cluster agent — whatever framework — is one Service label away from being cataloged ([ADR 0006](adr/0006-a2a-label-discovery.md)), so "we don't run kagent" is no longer an excuse. Unlabeled on-cluster agents are covered by heuristic discovery and the opt-in audit sweep; anything off-cluster or spawned at runtime remains dark — for those, an org **LLM gateway** is the honest instrument: usage that can't be attributed to any cataloged agent is itself the shadow-agent signal. |
 
 ## Lifecycle: every transition is a PR
 
@@ -60,7 +60,7 @@ payoff of using well-known kinds ([ADR 0002](adr/0002-component-not-custom-kind.
 | **Guessing their interface** | `agentcatalog.io/card-source=synthesized\|stale` — catalog can't confirm what they serve |
 | **Deprecated model** | Resources of type `llm-model-config` whose `agentcatalog.io/model` is on your sunset list; walk `dependsOn` back to affected agents |
 | **Over-privileged** | Agents whose `dependsOn` includes tool servers outside an allowlist |
-| **Discovered but unclaimed** | `agentcatalog.io/discovery=label` with owner still the `defaultOwner` — found, but nobody's name is on it |
+| **Discovered but unclaimed** | `agentcatalog.io/discovery=label\|probe\|heuristic` with owner still the `defaultOwner` — found, but nobody's name is on it |
 | **Drift (roadmap)** | Declared `a2aConfig` skills ≠ skills in the live card |
 
 ## What genuine hardening adds (beyond this MVP)

diff --git a/docs/release-checklist.md b/docs/release-checklist.md
@@ -1,64 +1,38 @@
-# v0.1.0 release checklist
+# Release Readiness
 
-Framing: **technical preview** — same honesty we extend to kagent and ARK.
-The product surface is further along than the packaging; this list is the
-packaging.
+This is the short checklist for each public package release. The detailed
+publishing setup and trusted-publisher instructions live in
+[releasing.md](releasing.md).
 
-## P0 — the repo must stand alone
+## Before The Release PR
 
-- [x] **Root yarn workspace** over `plugins/*` — `package.json` (workspaces),
-  `.yarnrc.yml`, root `tsconfig.json`, `packageManager: yarn@4.13.0`.
-  - [x] **`yarn.lock` committed** — `git clone && yarn install` is
-    reproducible. Full toolchain verified standalone: `yarn tsc`, `yarn lint`,
-    `yarn test` (52 passed), `yarn build`.
-- [x] **CI** (GitHub Actions): `.github/workflows/ci.yml` runs tsc, lint,
-  test, build on Node 20 & 22 with `yarn install --immutable`.
-  - [x] CI + license badges in the README.
-- [x] **Real package names** — `@showcall/backstage-plugin-agent-catalog` and
-  `@showcall/backstage-plugin-catalog-backend-module-agent-catalog`, with
-  repository/homepage/bugs/keywords and `publishConfig.access: public`.
-  - [x] Release workflow wired: `.github/workflows/release.yml` publishes both
-    packages on a `v*` tag via **npm Trusted Publishing (OIDC)** — no token,
-    automatic provenance. `publishConfig` verified against real tarballs
-    (frontend is ESM-only: `main` → `dist/index.esm.js`). Process documented
-    in [releasing.md](releasing.md).
-  - [ ] **Owner actions to enable publishing** (see [releasing.md](releasing.md)):
-    create npm org `showcall`; bootstrap the first publish of each package
-    manually (npm can't configure a trusted publisher for a nonexistent
-    package); then add the GitHub trusted publisher in each package's npm
-    settings.
-- [x] **Config schema (`config.d.ts`)** for every `agentCatalog.*` key, wired
-  via `configSchema` + `files`.
+- [ ] All intended feature and fix PRs are merged into main.
+- [ ] The root CHANGELOG.md has clear entries under Unreleased.
+- [ ] Each published-package change has an explicit Changeset.
+- [ ] yarn changeset status reports the intended bump for both packages.
 
-## P1 — the stranger's first hour
+## In The Release PR
 
-- [x] **Compatibility statement**, loud and early in the README (new
-  frontend system only; Node 20/22; client-node 1.x; kagent v1alpha2; ARK
-  v1alpha1 preview; LiteLLM usage).
-- [ ] **Screenshots in the README** — fleet page and the agent card, static
-  PNGs until the screen recording lands.
-- [x] **Ship a least-privilege RBAC manifest** — `deploy/rbac.yaml` (read-only
-  ClusterRole: services/endpoints list, services/proxy get, deployments list,
-  kagent + ARK CR reads).
-- [x] **CONTRIBUTING.md** (workspace dev setup, test loop, ADR convention) and
-  **SECURITY.md** (private vuln reporting; reads cluster state + spend ledgers).
-  - [x] Minimal GitHub issue templates (`.github/ISSUE_TEMPLATE/` — bug,
-    feature, config with security link).
+- [ ] Both public package versions remain in lockstep.
+- [ ] The generated version matches the release intent: a 0.x minor for a new
+  capability, or a patch for a compatible fix.
+- [ ] The changelog entry accurately describes user-visible behavior and any
+  operational or configuration considerations.
+- [ ] CI passes: typecheck, lint, tests, and package build.
+- [ ] Demo and documentation steps still match the released behavior.
 
-## P2 — tagging the release
+## Publishing
 
-- [x] CHANGELOG.md seeded (Keep a Changelog format, `Unreleased` section).
-- [ ] Tag `v0.1.0`, GitHub release notes with the technical-preview framing.
-- [ ] Repo topics (`backstage-plugin`, `a2a`, `ai-agents`, `kagent`) for
-  discoverability.
+- [ ] Merge the release PR.
+- [ ] Confirm the package version and tag match exactly.
+- [ ] Push vX.Y.Z and watch the Release workflow publish both packages.
+- [ ] Confirm the GitHub Release and npm package pages after the workflow
+  completes.
 
-## Known-and-accepted for v0.1 (state in release notes)
+## Current Boundaries
 
-- Audit sweep is opt-in and off by default ([ADR 0007](adr/0007-audit-sweep.md)).
-- Dapr Agents / Tier C not started ([roadmap](roadmap.md)).
-- Scaffolder output shows a raw `${{ steps.pr.output.remoteUrl }}` link
-  (cosmetic; the PR is created correctly).
-- ~~Provider wiring has no mocked-client tests yet~~ — **done in 0.2**: the
-  four entity providers now have mocked-kube-client `refresh()` tests (72 tests
-  total). This was the main 1.0 quality gate.
-- Legacy-frontend UI variant not available.
+- The audit sweep is opt-in and off by default because it probes declared
+  Service ports (ADR 0007).
+- Dapr Agents and hosted registry sources remain future work.
+- The frontend requires Backstage's new frontend system; the backend module
+  remains usable without the frontend package.