Skip to main content
← Back to list
01Issue
FeatureClosedSwamp Club
AssigneesNone

Relationships

#1355 docs: update giga-swamp guides and skills for setup extension --namespace

Opened by stack72 · 7/23/2026

Context

The setup extension --namespace flag shipped in core PR #1923. This lets users set the namespace at connect time, avoiding the contamination-prone namespace set + namespace migrate flow on shared prefixes. That old flow caused 9 production bugs (#1277, #1314, #1320, #1321, #1325, #1328, #1329, #1342, #1343). All are now fixed, but the docs and skills still recommend the old flow.

What needs updating

Swamp core repo — skills

.claude/skills/swamp/references/repo/references/namespaces.md

The "Multi-Repo Workflow" section currently says:

# Repo 1 (infra):
swamp datastore namespace set infra
swamp datastore namespace migrate --confirm
swamp datastore sync --push

Replace with:

# Repo 1 (infra):
swamp datastore setup extension @swamp/s3-datastore \
  --namespace infra \
  --config '{"bucket":"shared-bucket","prefix":"swamp","region":"us-east-1"}'

Add a note that namespace set + namespace migrate is only needed when converting an existing solo repo.

.claude/skills/swamp/references/share/guide.md

State 2 datastore table shows setup extension without --namespace. When setting up a shared datastore, the skill should ask if a namespace is needed and include --namespace if so.

Swamp-club repo — manual pages

content/manual/how-to/giga-swamp/set-up-giga-swamp.md — Primary setup guide. Change examples to use --namespace on setup extension. Remove the separate namespace set + namespace migrate --yes steps.

content/manual/how-to/giga-swamp/merge-repos.md — Both repos run setup extension without --namespace, then namespace set + namespace migrate. Update both to use --namespace.

content/manual/reference/datastore-configuration.md — Document --namespace <slug> as a flag on setup extension with description. Update examples. Add note in namespace section that --namespace on setup is preferred for new shared datastores.

content/manual/how-to/giga-swamp/add-namespace.md — Still valid for solo→namespace transition. Add note at the top: for new repos joining a shared datastore, use setup extension --namespace instead.

content/manual/explanation/giga-swamp.md — Check if it describes the setup flow. If so, update.

What NOT to change

The namespace set, namespace migrate, and namespace unset command documentation — those commands still exist and work for the solo→namespace transition. Just stop recommending them as the primary setup flow for new shared datastores.

02Bog Flow
✓OPEN○TRIAGED○IN PROGRESS◉CLOSED

Closed

7/23/2026, 12:42:41 AM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

stack72 commented 7/23/2026, 12:42:41 AM

Split into two repo-specific issues:

  • #1356 — swamp core repo (skills update)
  • #1357 — swamp-club repo (manual pages update)

Sign in to post a ripple.