finding: a bundle defining only a declaration, never instantiated, yields an empty catalog silently

[sagi5060]

Area: Authoring (Agent / Workflow / declarations)

What was observed

A project bundle that defines only an AgentDeclaration subclass, without instantiating an Agent, contributes nothing to the catalog. No error, no warning — from_project() returns an empty agents mapping.

Reproduction

# .agentdeck/agents/ghost/agent.py
from agentdeck.authoring import AgentDeclaration

class Ghost(AgentDeclaration):
    instructions = "boo"

from agentdeck import Deck
print(dict(Deck.from_project("./.agentdeck").build().agents))

Evidence — verbatim

from_project agents: {}

Version, commit, or branch

feat/164-deck-composition-api · PR #165 · report at aa2d3c5

Reference

• docs/delivery/beta-user-report-v3.md (N4)
• agentdeck/runtime/registry.py — PluginRegistry._scan, isinstance(attr, base_class) where base_class is Agent, not AgentDeclaration
• PR feat!: Deck — the v3 composition API, authoring/, and the end of App (#164) #165 review, non-blocking finding 7 (flagged statically; this is the empirical confirmation)
• Issue phase 4: Deck — the v3 composition API, authoring/, and the end of App #164 §4a — the BaseAgent → AgentDeclaration rename

How do you know?

I ran it and saw this happen.

Why it might matter

Under v1, a bare subclass was the agent — PluginRegistry scanned for subclasses. v3 scans
for instances. So the natural port of an existing bundle produces exactly this file, and the
result is an empty deck with no diagnostic pointing anywhere. This is the one migration trap I
hit that gives the user nothing to work with.

What is not yet known

• Would erroring on "bundle module imported cleanly and yielded no instance" produce false positives on legitimate shared-code modules inside a bundle directory?
• Does the same hole exist for WorkflowDeclaration?
• Is a warning enough, or does this need to fail build()?
• How many existing v1 bundles in the wild are shaped this way?

How far does it reach

Anyone using this feature.