docs: document FIRST_TREE_AGENT_TEMPLATE_PUBLISHER_ORG_ID in .env.example (ACE-38)

[Gandy2025]

Why

FIRST_TREE_AGENT_TEMPLATE_PUBLISHER_ORG_ID decides which Team may maintain
the official Agent Template catalog, but it was absent from .env.example.
An operator bringing up a deployment had no way to discover it short of
reading packages/shared/src/config/server-config.ts — or hitting a 403.

Leaving it unset fails closed in two places, and only one of them is obvious:

• requireAgentTemplatePublisher rejects every publisher-API request with
  403 "Agent Template publishing is not configured on this deployment."
• buildAdoptedTemplateSummaries cannot prove any adopted Template is
  public-safe without a publisher Team, so it degrades all of them to
  missing — which Agent Detail renders as an Unavailable badge. Users of
  a deployment that simply forgot the variable see broken-looking state on
  agents that are in fact fine.

The public read-only catalog keeps working either way; that is worth stating
too, so nobody sets the variable expecting it to gate /templates.

What

One commented entry in the Server (SaaS internal) — Optional block of
.env.example covering what the variable selects, that membership is
re-read per request (so grants and revocations take effect immediately), and
both failure modes above.

Config-example only — no source, schema, or behavior change.

Refs ACE-38.

[baixiaohang]

Recommendation: request changes

• Rationale: The new example is accurate, but it leaves the repository's canonical environment-variable reference incomplete.

Risk level: B-low

• Path baseline: .env.example is otherwise-unmatched configuration documentation -> C.
• Semantic lift: deployment-facing server configuration documentation -> B-low.

PR summary

• Author / repo: Gandy2025 / agent-team-foundation/first-tree
• Problem: Deployment operators cannot discover the Team that governs official Agent Template publishing, and an omitted setting produces both publisher-API denial and misleading unavailable responsibilities on Agent Detail.
• Approach: Document the publisher Team, live membership re-check, fail-closed behaviors, and unaffected public catalog next to the optional server settings.
• Impacted modules: .env.example deployment configuration guidance.

Review findings
❌ 1. Add this variable to the canonical environment-variable reference as well. The repository contract says the full env catalog lives in docs/cli-reference.md (AGENTS.md:36), whose SaaS server ops section begins at docs/cli-reference.md:1982 and still omits FIRST_TREE_AGENT_TEMPLATE_PUBLISHER_ORG_ID. As written, operators using the canonical reference remain unable to discover the setting, while the detailed semantics exist only in the secondary example. Please add the variable there and keep the publisher-Team, live-membership, and fail-closed behavior aligned with this new entry. [R1 / .env.example:56]
✅ 2. The added explanation matches the current authorization guard, adopted-Template projection, and public route behavior. [packages/server/src/services/agent-templates.ts:61]

Action taken

• Submitted request changes.

[yuezengwu]

Requesting changes: please also add FIRST_TREE_AGENT_TEMPLATE_PUBLISHER_ORG_ID to docs/cli-reference.md, which the repository-level AGENTS.md defines as the home of the full environment-variable reference. The new .env.example entry is accurate, but the operator-discoverability goal remains incomplete while the canonical reference omits it. Keep the publisher-Team scope, per-request membership re-check, both fail-closed effects, and the unaffected public catalog aligned between the two locations.

No other findings. This is documentation-only; I did not run tests.

[Gandy2025]

Addressed in f62725c — both reviews asked for the same thing.

docs/cli-reference.md now has an Agent Template publishing block in the
Server (SaaS internal) section, next to the other deployment-authority
settings (GitLab egress, GitHub App). It carries the same contract as the
.env.example entry: publisher Team scope, per-request membership re-check
rather than JWT-cached role, both fail-closed effects (403 on
/api/v1/internal/agent-templates, and adopted Templates degrading to an
Unavailable badge on Agent Detail), and the public catalog staying available
either way.

Two clarifications I added beyond the .env.example wording, since the
reference is where operators land first: official Skill bundles must be
attachments owned by the same Team, and setting the variable publishes nothing
by itself — the catalog stays empty until a publisher admin actually publishes.

Still documentation-only; no source or behavior change.

[baixiaohang]

Recommendation: approve

• Rationale: The canonical environment-variable reference now documents the setting and stays aligned with the accurate .env.example guidance.

Risk level: B-low

• Path baseline: .env.example and docs/cli-reference.md are otherwise-unmatched documentation/configuration paths -> C.
• Semantic lift: deployment-facing server configuration documentation -> B-low.

PR summary

• Author / repo: Gandy2025 / agent-team-foundation/first-tree
• Problem: Deployment operators lacked a discoverable explanation of the Team-level authority behind official Agent Template publishing and the visible consequences of leaving it unconfigured.
• Approach: Document the variable in both the deployment example and the canonical server env reference, including live membership checks, both fail-closed effects, unaffected public discovery, bundle ownership, and the fact that configuration alone does not create catalog entries.
• Impacted modules: .env.example; docs/cli-reference.md.

Review findings
✅ 1. The previous blocking issue is resolved: docs/cli-reference.md now includes the variable in the SaaS server ops reference and covers the same operational contract as .env.example. [docs/cli-reference.md:2042]
✅ 2. The added Publisher-Team bundle-ownership and explicit-publish clarifications match the current service boundaries. [packages/server/src/services/agent-templates.ts:212]

Action taken

• Approved.

[yuezengwu]

The original discoverability blocker is resolved, but one factual HTTP-contract issue remains. Both new entries say the unconfigured publisher API returns 403 for everyone / every request. These routes run inside userAuth, and packages/server/src/__tests__/agent-templates.test.ts explicitly asserts that an unauthenticated maintenance request returns 401; the publisher guard returns the documented 403 only after a valid user JWT reaches it.

Please narrow both .env.example and docs/cli-reference.md to every authenticated publisher-API request / all authenticated callers. That keeps the operator reference from misclassifying missing or invalid authentication as missing publisher configuration.

No other findings. This is documentation-only; I did not run tests.

[baixiaohang]

Recommendation: request changes

• Rationale: Both documentation entries currently overstate the unconfigured response as 403 for every request, although unauthenticated maintenance requests fail earlier with 401.

Risk level: B-low

• Path baseline: .env.example and docs/cli-reference.md are otherwise-unmatched documentation/configuration paths -> C.
• Semantic lift: deployment-facing server configuration documentation -> B-low.

PR summary

• Author / repo: Gandy2025 / agent-team-foundation/first-tree
• Problem: Deployment operators need a discoverable and accurate explanation of the authority behind official Agent Template publishing and its fail-closed behavior.
• Approach: Document the publisher Team setting in both the deployment example and canonical env reference.
• Impacted modules: .env.example; docs/cli-reference.md.

Review findings
❌ 1. Narrow the 403 claim in both locations to authenticated publisher-API requests/callers. The maintenance routes run inside userScope, and the existing test explicitly asserts that an unauthenticated request returns 401 before the publisher guard runs. Saying "every request" / "everyone" currently misclassifies missing or invalid authentication as missing publisher configuration. [packages/server/src/__tests__/agent-templates.test.ts:161; R4 / .env.example:59, docs/cli-reference.md:2054]

Action taken

• Replaced my approval with request changes after validating the authentication boundary.