feat: stop TUI browsers from silently skipping the agent-facing surface

[YoungJinJung]

Summary

The agent-facing surface (JSON CLI + MCP) covers 6 of 27 catalog services, and nothing prevents that gap from widening. Every browser merged since the MCP work landed has shipped TUI-only, and there is no test that notices.

Evidence

On a563207:

surface	count
Catalog services / features (TUI)	27 / 38
Agent-facing resource commands	6
Parity or coverage test	none

The six exposed resources are backup-vaults, alarms, cloudtrail-events, ecs-rollout, elb-target-health, and rds-instances (internal/cli/resources.go, internal/cli/resources_operations.go). The remaining MCP tools — get_capabilities, get_command_schema, get_mcp_capabilities, plan_context_sync — are meta, not resource reads.

Browsers with no agent-facing counterpart include CloudFormation, Step Functions, EventBridge, DynamoDB, Auto Scaling, ElastiCache, KMS, ACM, SQS, S3, Secrets Manager, Route53, IAM, VPC, EKS, ECR, and FIS.

Why this matters now

Adding a browser currently means wiring ~8 TUI touchpoints (catalog.go, model.go, app.go, filter.go, keymap.go, messages.go, feature_submodel.go, screen_views.go). The agent surface is a ninth touchpoint that is easy to miss because nothing fails when you skip it.

Concrete live example: #324 (SNS browser) adds a full TUI browser and no unic resources sns-topics. That was not a deliberate scoping decision — I simply did not know the agent surface existed, because nothing in the build, tests, or docs pointed at it.

Each JSON resource is hand-written — a jsonEnvelope[T] wrapper, a per-resource DTO, and a loadXxx function variable — so the cost is real and the gap will not close by itself.

Proposed change

Two parts, guard first.

1. A parity test with an explicit allowlist. Walk domain.Catalog(), assert each feature either has an agent-facing command or appears in a documented agentSurfaceExempt map with a one-line reason. New browsers then fail the build until the author makes a deliberate call — expose it, or record why not.

This is the high-leverage half: it is small, it prevents recurrence, and it converts an invisible gap into a visible, reviewable list.

2. Fill incrementally, highest value first. Not one PR. Suggested order, by how much a raw AWS API bridge would struggle to reproduce the view:

• inspect — RunSecurityScan / RunChecklist already return serializable reports (SecurityScanReport{Findings, ScannerCount, Warnings, ScannedAt}); 10 rule packs behind one call
• ElastiCache, SNS — multi-call joins with partial-failure semantics
• CloudFormation, Step Functions — failure-first triage ordering
• The rest as demand appears

Non-goals

• Exposing all 89 read-only repository methods. The shipped design is ~11 curated tools and that is the right shape; this issue does not propose changing it.
• Widening mutation coverage. The confirmation gate in internal/cli/mutation.go correctly ports the TUI's type-the-name guard, and new mutations are out of scope here.

Checklist

• Add a catalog-to-agent-surface parity test with a documented exemption map
• Record every current gap as an exemption entry so the list is reviewable in one place
• Document the agent surface as a wiring step in CLAUDE.md / docs/architecture.*.md so it is visible when adding a browser
• Expose inspect as the first fill, reusing the existing report structs
• Run make test and make build

[YoungJinJung]

@Unic-bot: assign me

[github-actions]

@YoungJinJung has been assigned to this issue.

[YoungJinJung]

Progress on the checklist.

• Parity test with a documented exemption map — test: guard agent surface parity #361
• Every current gap recorded as an exemption entry (7 mapped + 31 exempt = 38 catalog features)
• Agent surface documented as a wiring step — CLAUDE.md, AGENTS.md, both architecture docs
• Expose inspect as the first fill — feat: expose the inspector rule packs to automation #363
• Remaining fills

Two things worth recording while they are fresh.

Inspector sits outside the guard. grep -c Inspector internal/domain/{model,catalog}.go → 0. It is a workflow, not a catalog feature, so #361's parity test cannot see it — a green guard does not mean full coverage. #363 pins the boundary with TestSecurityInspectorToolIsReadOnlyAndNotAResourceContract and says so in both architecture docs, but any future non-catalog surface will have the same blind spot.

Four exemptions are justified more weakly than they read. FeatureAutoScalingBrowser, FeatureEventBridgeRules, FeatureLambdaBrowser, and FeatureSQSBrowser all cite mutations as the reason. But FeatureECSExec — which opens an interactive shell, the most mutation-capable feature in the catalog — is mapped to a read-only ecs-rollout command. So the read path is separable; the real reason is the trailing "yet". SQS looks like the strongest next candidate: deepest-backlog-first ordering with DLQ relationships is precisely the curated view a raw API bridge cannot reproduce.

Suggested order for the rest, by that same criterion — how much a generic AWS API bridge would struggle:

1. SQS queue backlogs (join + ordering + DLQ edges)
2. ElastiCache (replication-group/cluster join with partial-failure semantics)
3. SNS (topic + subscription join; the repository methods already return ([]T, []error, error), which maps straight onto data/warnings)
4. CloudFormation and Step Functions (failure-first triage ordering)

[YoungJinJung]

Status reconciliation as of 2026-09-15:

• Merged: test: guard agent surface parity #361 added the catalog-to-agent-surface guard and documentation; feat: expose the inspector rule packs to automation #363 exposed the inspector rule packs.
• Open follow-ups: test: validate complete MCP CLI invocations #362 validates complete MCP CLI invocations; feat: expose SQS queues to automation #364 exposes SQS; feat: expose ElastiCache resources to automation #365 exposes ElastiCache; feat: expose SNS topics to automation #366 exposes SNS; feat: expose CloudFormation stacks to automation #367 exposes CloudFormation; feat: expose Step Functions executions to automation #368 exposes Step Functions.
• All six open PR heads have passing hosted checks and have been reviewed at their current SHAs. Each remains REVIEW_REQUIRED / merge-blocked pending an independent approving review, so no review was repeated and no merge was attempted.
• No additional fill was started while these overlapping issue feat: stop TUI browsers from silently skipping the agent-facing surface #360 branches are in flight. The issue should remain open until the accepted follow-ups land and the remaining exemption list is reassessed.

[YoungJinJung]

Review-state update as of 2026-09-16: #365, #366, and #368 now have approvals from youngjinjung-linq on their unchanged heads. The collaborator-permission API reports that account has only read access, and GitHub still reports REVIEW_REQUIRED / BLOCKED for all six open follow-ups (#362, #364–#368). Main requires one approving review; an eligible reviewer with write access other than the PR author is still needed.

All current hosted checks pass. No new actionable feedback from YoungJinJung is outstanding, and all six heads already have completed code reviews. No duplicate review, additional implementation, or merge was attempted. Issue #360 remains open while the existing follow-ups await eligible approval.

[youngjinjung-linq]

Status reconciliation as of 2026-09-21:

• All six open follow-ups (test: validate complete MCP CLI invocations #362 and feat: expose SQS queues to automation #364–feat: expose Step Functions executions to automation #368) now have an approval from youngjinjung-linq on their unchanged current heads; test: validate complete MCP CLI invocations #362 and feat: expose SQS queues to automation #364 gained those approvals after the prior issue update.
• Hosted checks pass on every current head, and GitHub reports each PR as mergeable but still REVIEW_REQUIRED / BLOCKED.
• The active agent account does not have push access, so its approvals do not satisfy the protected-branch requirement. An eligible reviewer with write access, other than the PR author, is still required.
• No new comments from YoungJinJung request changes, and every current head has already received a complete review. To avoid duplicate review or overlapping implementation, no code changes or merge attempts were made.

Issue #360 remains open while the existing follow-ups await eligible approval.