fix: 对齐 Agent 指针目录与客户端校验契约 (#103)

## 问题 / Problem

市场 CI 要求每个 Agent 条目都有 catalog sidecar，但 sidecar 校验器只接受相邻的
agent.json。客户端已支持的 Agent entry.json 指针因此无法满足完整覆盖门禁。

The catalog completeness gate requires sidecars for every Agent, while
the validator previously read only agent.json. Valid Agent pointer
entries could not satisfy CI.

## 修改 / Changes

- Agent 主文件严格二选一：内联 agent.json 或指针 entry.json；目录 slug 与安装源 UUID 保持分离。
- 使用从主仓固定提交导出的完整客户端 Agent entry Schema，先校验原始类型、字段、版本、路径和策略组合，再比较
sidecar。
- 对齐 latestVersion、固定来源、许可/治理、兼容性和有效的缺省 market/market 策略，拒绝 sidecar
单方面提升托管权限。
- 未修改产品条目、manifest、现有 sidecar Schema 或 CI 完整性要求。

Agent pointers now pass the pinned client input schema before source
metadata consistency checks. Effective default policies are compared
without promoting catalog metadata into authority. Existing inline
Agents and Skills retain their validation paths; no entries or CI
requirements change.

## 验证 / Validation

- 29 + 4 + 9 项定向 Python 测试通过。
- 完整 i18n、catalog --require-complete、translation freshness 检查通过；116
条既有警告与基线一致，无新增。
- 原始客户端 Schema 与固定主仓来源逐项比较一致（仅增加溯源注释）。
- 独立代码审查发现的原始契约与缺省策略问题已修复并复核。
- 公开信息边界检查覆盖完整工作树、隐藏文件、链接目标与新增 Git 元数据，通过。

Targeted tests, full catalog/i18n/freshness validation, source-schema
comparison and independent review passed. Existing warnings are
unchanged. This PR repairs catalog validation; it does not claim runtime
installation of a new product.

---------

Co-authored-by: yige <yige@yigedeMacBook-Neo.local>

README.md

@@ -143,6 +143,40 @@ surface for older clients. New clients merge the sidecar through a deterministic
 adapter. Any field repeated in both files must have the same value; the validator
 rejects drift rather than choosing one copy silently.
 
+Agent listings support exactly one of `agents/<slug>/agent.json` (inline metadata)
+or `agents/<slug>/entry.json` (an external pointer), alongside the sidecar. Missing
+or simultaneous primary files are rejected. For a pointer, `entry.id` and sidecar
+`identity.id` use the catalog directory slug and `identity.kind` is `agent`; the
+upstream AgentFS `agent.json.id` remains its own UUID and must not be rewritten.
+
+Agent pointers first pass the complete raw client contract in
+[`schemas/market-agent-entry.client.schema.json`](schemas/market-agent-entry.client.schema.json),
+exported from `marketAgentEntrySchema` in the DesireCore repository at commit
+`18bbb86f62e1288b1f945209bed74ec72620a9d4`. The schema's `$comment` records the
+source blob as well. Refresh this generated snapshot from the TypeScript export
+when changing client compatibility; do not replace it with permissive sidecar
+validation. Version fields keep their original types and the client's supported
+format. Installation/update policies must either both be absent (effective
+`market/market`) or form a complete supported pair; the sidecar must preserve
+that effective pair.
+
+Agent pointer `latestVersion` maps to sidecar `release.version`; optional
+`requiredClientVersion`, `installPolicy`, and `updatePolicy` must agree with the
+sidecar compatibility/spec fields. Pointer source fields must describe the same
+artifact as `provenance.content`, and `maintainer` maps to `upstreamMaintainer`.
+An installable Agent pointer must itself pin `source.ref` (Git) or `source.sha256`
+(Web/ZIP); an immutable ref supplied only by the sidecar cannot pin a mutable
+entry. Existing immutable-source, license, governance-review and complete-coverage
+checks still apply. Agent pointers do not receive the built-in Skill exceptions.
+
+Agent 目录必须在 `agent.json` 内联元数据和 `entry.json` 外部指针中二选一，并提供 sidecar。
+Pointer 原始 JSON 先通过固定客户端提交导出的完整 Schema；版本类型与格式、来源路径和策略组合不能由 sidecar 掩盖。
+Pointer 的目录 slug、`entry.id`、sidecar `identity.id` 必须一致；上游 AgentFS 的 UUID 不改写。
+安装/更新策略双缺省时有效值仍是 `market/market`，sidecar 不得将其改成系统条目。
+`latestVersion`、最低客户端版本和安装/更新策略须与 sidecar 对齐；来源必须是同一个制品。
+可安装指针自身必须固定 Git ref 或 Web/ZIP 摘要，不能只在 sidecar 宣称不可变版本。
+现有许可、治理审查、不可变来源和完整覆盖门禁继续有效，不适用内置 Skill 的宽松例外。
+
 The sidecar records source-owned presentation, release, timestamp, content
 provenance, governance, compatibility, and type-specific facts. It deliberately
 cannot declare `catalogSourceId`, catalog commit/path/trust, effective official