#551 docs: giga-swamp user documentation — reference, how-to, and conceptual guide

Problem

Giga-swamp is feature-complete (Phases 1-7 shipped) but has no user-facing documentation. Users have no way to discover the feature, understand what it enables, or learn how to set it up. The only documentation is the internal design doc at resources/giga-swamp.md which is written for implementers, not users.

What needs to be documented

1. Conceptual guide — What is giga-swamp?

Explain the problem (multiple repos, one datastore, correlated findings) and the solution (namespaces as provenance, not isolation). Cover:

• What a namespace is and what it means (bounded context identifier, not a security boundary)
• Solo mode vs giga-swamp mode — when you need namespaces and when you dont
• Provenance not isolation — everything is visible, namespaces answer who produced this
• Secrets and vaults stay repo-local (exception to sharing)
• Known v1 limitations: no cross-namespace workflow steps, no cross-namespace GC, no foreign catalog TTL

2. How-to guides

Step-by-step guides for common tasks:

• Setting up a new giga-swamp from scratch (two repos, one S3 bucket)
• Adding a namespace to an existing solo repo (namespace set + migrate)
• Querying across namespaces with CEL (ns:model syntax, *:model wildcard, ns predicate in data.query)
• Pulling foreign catalog metadata (swamp datastore catalog pull --namespaces)
• Listing and managing namespaces (swamp datastore namespaces, namespace set/unset)
• Removing a namespace and returning to solo mode (namespace unset --migrate)
• Merging two solo repos into a shared datastore

3. Reference documentation

CLI command reference for all new commands:

• swamp datastore namespace set — options, behavior, warnings
• swamp datastore namespace unset — guards, --migrate flag
• swamp datastore namespace migrate — dry-run, --confirm, --reverse, what gets moved
• swamp datastore namespaces — output format, --json
• swamp datastore catalog pull --namespaces — what it fetches, staleness

CEL query reference updates:

• ns:model prefix syntax for cross-namespace point lookups
• *:model wildcard syntax with ambiguity error behavior
• ns field in data.query() predicates (note: ns not namespace — CEL reserves namespace)
• Default scoping: point lookups = own namespace, data.query() = all namespaces

Configuration reference:

• namespace field in .swamp.yaml datastore config
• SWAMP_NAMESPACE env var (if applicable)
• .namespace.json manifest format

4. Design doc updates

• resources/giga-swamp.md — mark all phases as shipped, update status
• design/datastores.md — ensure namespace-scoped sync is documented

Context

All giga-swamp phases shipped:

• Phase 1: Namespace value object + config (#464)
• Phase 2: Catalog schema v4 (#479)
• Phase 3: Path resolver + locking (#486)
• Phase 4: CEL cross-namespace queries (#516)
• Phase 5: CLI output + namespace commands (#542)
• Phase 6: Namespace-scoped sync (#525)
• Phase 7: Data migration commands (#548)
• S3/GCS extensions: Namespace-scoped sync + manifest support (#533, #547)