Docs: How to clear previously set attributes for a blueprint

[scottschreckengaust]

Doc area

Developer guide (docs/guides/DEVELOPER_GUIDE.md or synced site)

Describe the issue

Non-blocking, follows the existing pattern for every other optional Blueprint field (maxTurns, modelId, systemPromptOverrides all behave identically): because the onUpdate UpdateExpression only SETs the attribute when the prop is present, removing maxBudgetUsd from a Blueprint and redeploying leaves the old max_budget_usd value in the DynamoDB row — the repo keeps its budget cap until someone deletes the attribute out-of-band. Same story on the CLI side: repo-onboard.ts preserves an existing value. Not a defect in this PR (fixing it would mean REMOVE-clause plumbing across all optional fields), but if the docs ever grow a "how do I unset a per-repo budget" question, this is the answer — worth a line in a future docs pass or a tracked issue.

Affected docs

#763 (comment)

Suggested change

No response

[theagenticguy]

Follow-up analysis from the review thread that spawned this issue — what clearing mechanism already exists, where the fix and the docs belong, and what the docs currently say (verified on 17cd942, the PR #763 head).

The repo already has a clearing mechanism — for lists

The precedent is in cdk/src/constructs/blueprint.ts itself. For the three registry asset fields (#246), onUpdate computes which lists are now empty and appends a REMOVE clause instead of just omitting them from SET:

• emptyAssetFields() / buildRemoveClause() / buildRemoveNames() — blueprint.ts:487-505
• The in-code rationale: "Registry asset fields that are now empty must be REMOVEd on update, not just omitted from SET — otherwise a redeploy that cleared the last mcp_server/cedar_policy_module/skill leaves the stale DDB refs active and operators can't detach a pinned asset through the Blueprint API (feat(registry): central agent asset registry for capabilities, skills, plugins, and MCP servers #246)."
• Pinned by tests at cdk/test/constructs/blueprint.test.ts:431-449, including the exact clause REMOVE #cedar_policy_modules, #skills.

So the code fix (if wanted beyond docs) is mechanical: extend the same pattern to the optional scalars — when maxBudgetUsd / maxTurns / modelId / systemPromptOverrides / pollIntervalMs / etc. are undefined at onUpdate, add the attribute to the REMOVE clause. That makes the Blueprint fully declarative: the construct's props become the whole truth of the row.

One design question it raises: mixed ownership. bgagent repo onboard also writes these rows and deliberately preserves an existing budget on re-onboard (cli/src/repo-onboard.ts:116). A declarative CDK Blueprint would clobber a CLI-set value on redeploy. The asset lists already behave declaratively, so extending to scalars makes the construct consistent rather than introducing a new hazard — but the ownership rule ("once a repo has a CDK Blueprint, CDK owns the row") should be stated wherever this lands.

Where the documentation belongs

Two homes, one per audience:

Audience	Location	What goes there
Design truth	docs/design/REPO_ONBOARDING.md (~line 82, the lifecycle paragraph)	Create = full PutItem; update = SET present props (+ REMOVE for cleared asset lists, today); which fields are sticky
Operators	docs/guides/USER_GUIDE.md → "Where can I set max_budget_usd?" (+ Starlight mirror customizing/Per-repo-overrides.md)	"How do I unset a per-repo budget" — today the honest answer is: set it to a new value, or delete the attribute out-of-band; removing the prop and redeploying does not clear it

Is it documented anywhere today? No — and one existing sentence overstates

Grepped the full docs tree: the SET-vs-REMOVE asymmetry appears only as the code comment and the tests, never in any Markdown. Even the #246 REMOVE behavior for asset lists never made it into REGISTRY.md or the onboarding doc.

Worse, docs/design/REPO_ONBOARDING.md:82 currently says:

Redeploying with updated props overwrites the record.

That is only true for onCreate (full PutItem) and for props that are present. For an optional prop you removed, the onUpdate path does not overwrite anything — the old value survives.

Suggested resolution (two legs)

1. Docs (this issue's scope): correct the REPO_ONBOARDING.md:82 lifecycle sentence to state the actual update semantics, and add the "how do I unset" line to the User Guide budget section + mirror. Run mise //docs:sync.
2. Optional code follow-up (separate issue if wanted): extend the feat(registry): central agent asset registry for capabilities, skills, plugins, and MCP servers #246 REMOVE-clause pattern to optional scalar fields, with tests mirroring blueprint.test.ts:431-449, and decide/document the CDK-vs-CLI row-ownership rule explicitly.