#3235 Docs: update Kiro and Amp how-to pages for the new scaffolding (swamp-club#3222)

swamp-club#3222 changes what swamp repo init / repo upgrade write for Kiro and Amp. Two manual pages under content/manual/how-to/ai-agents/ describe the old files and need updating once that ships.

kiro.md

"What this sets up" (currently says six files and lists .vscode/settings.local.json and .kiro/hooks/swamp-audit.kiro.hook):

• Remove .vscode/settings.local.json (trusted swamp * commands). Kiro IDE 1.0 no longer reads kiroAgent.trustedCommands / kiroAgent.commandDenylist, so swamp no longer writes them.
• Replace .kiro/hooks/swamp-audit.kiro.hook with .kiro/hooks/swamp-audit.json: a Kiro v1 hook (PostToolUse) that records commands via swamp audit record --from-hook --tool kiro. Kiro IDE 1.0 runs it, and it is IDE-facing now (the legacy .kiro.hook no longer runs in IDE 1.0).
• .kiro/agents/swamp.json: the tool list is now glob, grep, read, shell, thinking, todo_list, write. It is written in kiro-cli's universal format, which both the default 2.x engine and the opt-in 3.0 engine (kiro-cli --v3) load. It pre-approves swamp commands and blocks swamp vault read-secret (2.x toolsSettings plus 3.0 permissions.rules). The audit hook is now an array entry.
• Note that Kiro IDE ignores agent configs that contain hooks, so the swamp agent applies to kiro-cli only.

New: pre-approving swamp commands in Kiro IDE 1.0. IDE 1.0 reads permission rules only from outside the repository, so swamp cannot write them. A user who wants swamp commands to run without prompts in the IDE can add a rule to ~/.kiro/settings/permissions.yaml, or choose "Always allow" for the workspace when prompted, e.g.:

rules:
  - capability: shell
    match: ["swamp *"]
    exclude: ["*read-secret*"]
    effect: allow

Ref: https://kiro.dev/docs/permissions/

"Upgrading" (currently: "The steering file, agent config, and .kiro.hook are overwritten … .kiro/settings/cli.json and .vscode/settings.local.json are merged"):

• The steering file, agent config and .kiro/hooks/swamp-audit.json are overwritten with the latest versions; .kiro/settings/cli.json is merged.
• Upgrade removes swamp's legacy .kiro/hooks/swamp-audit.kiro.hook, and removes copies of the audit hook that Kiro IDE auto-migrated into other .kiro/hooks/*.json files. Only swamp's exact hook entry is removed, and a file is deleted only if nothing else is left in it.
• Upgrade removes swamp's own entries (swamp *, read-secret) from .vscode/settings.local.json, keeping your entries and other settings, and deletes the file only if nothing is left.

Known limit worth a sentence: under the opt-in kiro-cli 3.0 engine, both the agent's hook and .kiro/hooks/swamp-audit.json run, so a shell command may appear twice in swamp audit.

amp.md

"What this sets up" (currently says swamp writes .amp/settings.json with swamp * in the trusted command allowlist):

• Amp no longer reads amp.commands, and runs tools without asking by default. Swamp now writes a managed Amp plugin, .amp/plugins/swamp.ts. It asks before any shell command containing read-secret runs (e.g. swamp vault read-secret), and refuses it when nobody can answer (e.g. amp --execute). Every other tool call runs as normal.

"Upgrading" (currently mentions .amp/settings.json being preserved/merged):

• .amp/plugins/swamp.ts is overwritten with the latest version.
• Upgrade removes swamp's swamp * entry from amp.commands.allowlist, keeping your entries and settings. It drops the amp.commands block when nothing but strict is left, and deletes .amp/settings.json only if nothing is left in it.

Refs: swamp-club#3222, swamp-club#3219, swamp-uat#609.