feat(cli): operator commands for repos, platform introspection, and day-2 ops (#378) (#385)

* feat(cli): add additional commands

* feat(cli): add additional commands

* feat(cli): address self review

* fix(cli): redact secret ARN in repo JSON output + address review feedback

MAJOR (PR #385 review):
- Redact github_token_secret_arn in repo list/onboard/offboard --output json
  (repo show already redacted; the sibling JSON paths emitted raw rows)
- Correct docs over-claim that 'all operator commands accept --output json'
  (github set-token/set-webhook-secret + admin invite/delete/reset have no
  --output; admin list-users does) across README + USER_GUIDE + mirrors

Minor:
- Command-level tests for repo list/show/onboard/offboard JSON redaction + wiring
- Fix stale ./QUICK_START.md links (.md -> .mdx) in DEPLOYMENT/DEVELOPER guides
  and REPO_ONBOARDING design doc
- Extract duplicated documentClient/lowLevelClient into dynamo-clients.ts
- webhook test: best-effort --repo validation degrades to a warning when AWS
  context is unavailable (pure --api-url + --secret path needs no AWS access)

563 tests pass, lint clean, docs mirrors re-synced (idempotent).

* fix(deps): bump pydantic-settings to 2.14.2 for GHSA-4xgf-cpjx-pc3j

Constrain the transitive mcp dependency to the patched release so
security:deps passes on PR #385.

Co-authored-by: Cursor <cursoragent@cursor.com>

* docs(cli): address re-review — ADR-017, onboarding doc, link fixes

Reconcile REPO_ONBOARDING.md with the operator CLI write path and add
ADR-017 documenting the trade-off and deferred audit trail. Fix remaining
QUICK_START.md → .mdx references and reject backslash in Cognito email
lookup filter guard (+2 tests).

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: bgagent <bgagent@noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

CONTRIBUTING.md

@@ -14,7 +14,7 @@ Describe what you intend to contribute. This avoids duplicate work and gives mai
 
 ### 2. Set up your environment
 
-Follow the [Quick Start](./docs/guides/QUICK_START.md) to clone, install, and build the project. See the [Developer guide](./docs/guides/DEVELOPER_GUIDE.md) for local testing and the development workflow.
+Follow the [Quick Start](./docs/guides/QUICK_START.mdx) to clone, install, and build the project. See the [Developer guide](./docs/guides/DEVELOPER_GUIDE.md) for local testing and the development workflow.
 
 Use **[AGENTS.md](./AGENTS.md)** to understand where to make changes (CDK vs CLI vs agent vs docs), which tests to extend, and common pitfalls (generated docs, mirrored API types, `mise` tasks).
 

agent/pyproject.toml

@@ -52,6 +52,7 @@ dependencies = [
 [tool.uv]
 constraint-dependencies = [
     "pyjwt>=2.13.0",  # PYSEC-2026-175/177/178/179 — transitive via mcp; remove when mcp bumps floor (#267)
+    "pydantic-settings>=2.14.2",  # GHSA-4xgf-cpjx-pc3j — transitive via mcp; remove when mcp bumps floor
 ]
 
 [tool.bandit]

agent/uv.lock

@@ -19,33 +19,30 @@ node cli/lib/bin/bgagent.js
 After deploying the stack (`cd cdk && npx cdk deploy`), extract the outputs and configure the CLI:
 
 ```bash
-# 1. Extract stack outputs into environment variables
-STACK_NAME="backgroundagent-dev"
-API_URL=$(aws cloudformation describe-stacks --stack-name $STACK_NAME \
-  --query 'Stacks[0].Outputs[?OutputKey==`ApiUrl`].OutputValue' --output text)
-USER_POOL_ID=$(aws cloudformation describe-stacks --stack-name $STACK_NAME \
-  --query 'Stacks[0].Outputs[?OutputKey==`UserPoolId`].OutputValue' --output text)
-APP_CLIENT_ID=$(aws cloudformation describe-stacks --stack-name $STACK_NAME \
-  --query 'Stacks[0].Outputs[?OutputKey==`AppClientId`].OutputValue' --output text)
-
-# 2. Configure the CLI
-bgagent configure \
-  --api-url "$API_URL" \
-  --region us-east-1 \
-  --user-pool-id "$USER_POOL_ID" \
-  --client-id "$APP_CLIENT_ID"
+# 1. Print stack outputs (replaces manual aws cloudformation describe-stacks)
+bgagent platform outputs --stack-name backgroundagent-dev
+
+# 2. Store the GitHub PAT (replaces aws secretsmanager put-secret-value)
+bgagent github set-token --stack-name backgroundagent-dev
+
+# 3. Configure the CLI (reads ApiUrl, UserPoolId, AppClientId from the stack)
+bgagent configure --region us-east-1 --stack-name backgroundagent-dev
 
-# 3. Log in with your Cognito credentials
+# Or pass fields explicitly / use --from-bundle from `admin invite-user`
+
+# 4. Log in with your Cognito credentials
 bgagent login --username you@example.com
 
-# 4. Submit a task
+# 5. Submit a task
 bgagent submit --repo owner/repo --issue 42
 
-# 5. Check status
+# 6. Check status
 bgagent list
 bgagent status <task-id>
 ```
 
+Operator commands (`platform`, `repo`, `github set-token`) use **operator AWS credentials** directly — Cognito login is not required.
+
 ## Commands
 
 ### `bgagent configure`
@@ -54,12 +51,16 @@ Save API endpoint and Cognito settings to `~/.bgagent/config.json`.
 
 ```
 bgagent configure \
-  --api-url <url>         API Gateway base URL (required)
-  --region <region>       AWS region (required)
-  --user-pool-id <id>     Cognito User Pool ID (required)
-  --client-id <id>        Cognito App Client ID (required)
+  --stack-name <name>     Read ApiUrl, UserPoolId, AppClientId from CloudFormation
+  --from-bundle <base64>  All four fields from `bgagent admin invite-user`
+  --api-url <url>         API Gateway base URL (override or manual configure)
+  --region <region>       AWS region (required with --stack-name if unset in env)
+  --user-pool-id <id>     Cognito User Pool ID
+  --client-id <id>        Cognito App Client ID
 ```
 
+First-time configure needs all four core fields. The easiest paths are `--stack-name backgroundagent-dev --region …` (same outputs as `bgagent platform outputs`) or `--from-bundle` after `admin invite-user`. Individual flags override stack-derived values.
+
 ### `bgagent login`
 
 Authenticate with Cognito and cache tokens locally.
@@ -165,6 +166,162 @@ bgagent webhook revoke <webhook-id> \
   --output <text|json>         Output format (default: text)
 ```
 
+## Operator commands
+
+These commands support day-2 operations using **operator AWS credentials** (IAM profile or environment). They read CloudFormation outputs, DynamoDB, and Secrets Manager directly — no Cognito login required. The read-only and introspection commands (`platform`, `repo`, `runtime`, `ops`, `webhook test`, `admin list-users`) support `--output json` for scripting; the credential-writing commands (`github set-token`/`set-webhook-secret`, `admin invite-user`/`delete-user`/`reset-password`) do not.
+
+Shared flags:
+
+| Flag | Description |
+|------|-------------|
+| `--region <region>` | AWS region (defaults to `bgagent configure` region or `AWS_REGION`) |
+| `--stack-name <name>` | CloudFormation stack name (default: `backgroundagent-dev`) |
+
+### `bgagent platform outputs`
+
+Print CloudFormation stack outputs (`ApiUrl`, `UserPoolId`, `AppClientId`, `GitHubTokenSecretArn`, etc.).
+
+```
+bgagent platform outputs \
+  --output <text|json>         Output format (default: text)
+```
+
+### `bgagent platform doctor`
+
+Smoke-check deployed platform readiness: Task API reachable, Cognito pool/client valid, platform GitHub token populated, at least one active onboarded repo, Bedrock model visible.
+
+```
+bgagent platform doctor \
+  --output <text|json>         Output format (default: text)
+```
+
+Exits with code 1 when any check fails (warnings are acceptable).
+
+### `bgagent repo list`
+
+List repositories onboarded via Blueprint constructs (reads `RepoTable`).
+
+```
+bgagent repo list \
+  --status <active|removed>    Filter by status
+  --output <text|json>        Output format (default: text)
+```
+
+### `bgagent repo show <owner/repo>`
+
+Show full `RepoConfig` for a repository. Secret ARNs are redacted. When no per-blueprint token is configured, the output shows that the repo uses the **platform default** GitHub PAT (`GitHubTokenSecretArn`), not an empty/missing token.
+
+```
+bgagent repo show owner/repo \
+  --output <text|json>        Output format (default: text)
+```
+
+### `bgagent repo onboard <owner/repo>`
+
+Register or re-activate a repository in `RepoTable` without a CDK redeploy. With no overrides, tasks use the platform `RuntimeArn` and `GitHubTokenSecretArn` (IAM already granted at deploy). Custom `--runtime-arn` / `--token-secret-arn` values require matching `TaskOrchestrator` IAM via CDK — the command prints notes explaining this. Prefer CDK `Blueprint` constructs for durable lifecycle, Cedar policies, and egress validation.
+
+```
+bgagent repo onboard owner/repo \
+  --compute-type <agentcore|ecs> \
+  --runtime-arn <arn>         AgentCore runtime override (agentcore only) \
+  --model <model-id> \
+  --token-secret-arn <arn> \
+  --max-turns <n> \
+  --poll-interval <ms>        Default agent poll interval in milliseconds \
+  --output <text|json>
+```
+
+### `bgagent repo offboard <owner/repo>`
+
+Soft-delete a repository (`status=removed` + TTL), matching Blueprint delete semantics. An existing Blueprint will re-activate the repo on the next CDK deploy.
+
+```
+bgagent repo offboard owner/repo \
+  --output <text|json>
+```
+
+### `bgagent runtime status`
+
+Show **per-blueprint** effective compute substrate and runtime ARN (merged with platform `RuntimeArn`), then probe unique AgentCore runtimes via the control-plane API. ECS blueprints are listed separately — they use the platform ECS cluster/task definition, not per-repo `runtime_arn`.
+
+```
+bgagent runtime status \
+  --repo <owner/repo>         Limit to one repository \
+  --output <text|json>
+```
+
+### `bgagent ops stuck-tasks`
+
+List tasks in `SUBMITTED`, `HYDRATING`, or `AWAITING_APPROVAL` older than the stranded-task reconciler thresholds (defaults: 1200s / 7200s). Text output includes Cognito email plus username UUID.
+
+```
+bgagent ops stuck-tasks \
+  --stranded-timeout <seconds> \
+  --approval-timeout <seconds> \
+  --output <text|json>
+```
+
+### `bgagent ops concurrency`
+
+Compare `UserConcurrencyTable` counters with live active task counts per user. Resolves Cognito usernames to email (same as `bgagent admin list-users`).
+
+```
+bgagent ops concurrency \
+  --limit <n>                 Per-user limit (default: 3) \
+  --output <text|json>
+```
+
+### `bgagent webhook test <webhook-id>`
+
+Send a signed sample payload to `POST /v1/webhooks/tasks` (creates a real task — cancel afterward if this was only a connectivity check).
+
+```
+bgagent webhook test <webhook-id> \
+  --secret <secret>           From `webhook create` output \
+  --fetch-secret              Read secret from Secrets Manager (operator IAM) \
+  --repo <owner/repo>         Target repo (defaults to first active repo) \
+  --api-url <url>             Defaults to configure api_url or stack ApiUrl \
+  --output <text|json>
+```
+
+### `bgagent github set-token`
+
+Store a GitHub personal access token in Secrets Manager (interactive masked prompt).
+
+```
+bgagent github set-token \
+  --repo <owner/repo>         Target a blueprint's per-repo token secret (when configured)
+  --secret-arn <arn>          Write to an explicit Secrets Manager ARN
+  --region <region>           AWS region (defaults to configured region)
+  --stack-name <name>         CloudFormation stack name (default: backgroundagent-dev)
+```
+
+With no flags, writes to the platform default `GitHubTokenSecretArn` stack output. When `--repo` is used, the CLI reads `github_token_secret_arn` from `RepoTable` if the Blueprint configured `credentials.githubTokenSecretArn`; otherwise it falls back to the platform default with a notice.
+
+### `bgagent github webhook-info` / `set-webhook-secret`
+
+Configure the preview-deploy screenshot pipeline webhook. See [Deploy preview screenshots guide](../docs/guides/DEPLOY_PREVIEW_SCREENSHOTS_GUIDE.md).
+
+### `bgagent admin invite-user` / `list-users` / `delete-user` / `reset-password`
+
+Manage Cognito users with operator AWS credentials (`cognito-idp:Admin*` on the deployment user pool). Works **before** `bgagent configure` when `--stack-name` is passed (reads `UserPoolId` from CloudFormation).
+
+```
+bgagent admin invite-user <email> \
+  --stack-name backgroundagent-dev \
+  --password <pwd>              # optional; auto-generated if omitted
+
+bgagent admin list-users \
+  --output <text|json>
+
+bgagent admin delete-user <email>
+
+bgagent admin reset-password <email> \
+  --password <pwd>              # optional; auto-generated if omitted
+```
+
+`invite-user` creates the user, sets a permanent password, and writes credentials plus an optional configure bundle to `~/.bgagent/invites/<email>.txt` (mode 0600). Replaces Quick Start Step 5 raw `aws cognito-idp` commands.
+
 ## Output formats
 
 **Text mode** (default) prints human-readable output:

cli/README.md

@@ -32,8 +32,12 @@ import { makeLinearCommand } from '../commands/linear';
 import { makeListCommand } from '../commands/list';
 import { makeLoginCommand } from '../commands/login';
 import { makeNudgeCommand } from '../commands/nudge';
+import { makeOpsCommand } from '../commands/ops';
 import { makePendingCommand } from '../commands/pending';
+import { makePlatformCommand } from '../commands/platform';
 import { makePoliciesCommand } from '../commands/policies';
+import { makeRepoCommand } from '../commands/repo';
+import { makeRuntimeCommand } from '../commands/runtime';
 import { makeSlackCommand } from '../commands/slack';
 import { makeStatusCommand } from '../commands/status';
 import { makeSubmitCommand } from '../commands/submit';
@@ -74,6 +78,10 @@ program.addCommand(makeSlackCommand());
 program.addCommand(makeLinearCommand());
 program.addCommand(makeJiraCommand());
 program.addCommand(makeGithubCommand());
+program.addCommand(makePlatformCommand());
+program.addCommand(makeRepoCommand());
+program.addCommand(makeRuntimeCommand());
+program.addCommand(makeOpsCommand());
 program.addCommand(makeWatchCommand());
 program.addCommand(makeTraceCommand());
 program.addCommand(makeWebhookCommand());