#3965 docs(manual): the manual documents swamp subscription status and start — standings, call to action, flags and --json output

Summary

Document the swamp subscription command group in the swamp-club manual. The CLI shipped it in swamp-club#3950 (status, swamp #3372) and swamp-club#3951 (start); the manual has no page for it yet. Docs only: this lands in the swamp-club repo, and no CLI or API change is needed.

Changes

Add content/manual/reference/subscription-commands.md, modelled on content/manual/reference/issue-commands.md and invite-commands.md (front matter with title, description, type: reference, order; a short intro; one ## section per subcommand with a usage block and a flag table).

Intro: the swamp subscription group shows the plan and billing standing of the signed-in user and their collectives, and opens the swamp-club billing page. Running swamp subscription with no subcommand prints group help. Both subcommands need a swamp-club.com account like any other command (link Swamp Account Requirement), and both run outside a swamp repository.

swamp subscription status

Shows the plan and billing standing of the signed-in user and each collective they belong to. Makes one call to swamp-club, the same one swamp auth whoami makes, and words each collective exactly as whoami does.

• Example output (log mode):

  alice ([REDACTED-EMAIL]) on https://swamp-club.com
  Plan: Team
  Collectives:
    alice  trial: 9 days left (ends 2026-11-03)
    acme   Team  active
  
  To manage billing:  swamp subscription start

• Standings table — what a collective's line can say:

  Shown	Meaning
  Team, Business, Enterprise, then a status such as active	A paid plan; the billing status is shown to owners and admins only
  Personal License	A Personal License: free, for use outside of work; work use needs a paid plan
  Admin	Admin standing, set by Swamp Club; nothing to bill
  trial: N days left (ends YYYY-MM-DD)	A free collective on a running trial
  covered	A free collective allowed private extensions through another collective its owner belongs to
  trial ended	A free collective whose trial has ended
  slug only	A free collective with nothing else to say

  A paid collective is never shown as on a free trial; --json keeps the trial for billing triage.

• Plan: line: the strongest plan across the user's collectives, chosen by swamp-club (Admin, then any paid plan, then Personal License). Omitted when that is free.

• Call to action on the last line:

  • To upgrade: swamp subscription start when the strongest plan is free, absent, or a Personal License
  • To manage billing: swamp subscription start for a paid plan
  • none for Admin standing

• Collective API key (SWAMP_API_KEY): the first line is Collective token: <slug> on <server>, and only that collective is listed.

• Older or self-hosted swamp-club that does not report subscriptions: the identity line, then This Swamp Club server does not report subscriptions.; exit code 0.

• SWAMP_CLUB_URL: talks to that server instead of the one stored at login.

• --json: document every key — serverUrl, username (or collectiveSlug for a collective token), plan, planName (both null when absent), entitlementsReported, collectives (each with slug, plan, planName, subscriptionStatus (owners and admins only), trial and privateExtensions, as swamp-club sent them), and billingUrl. Include an example document. When the server reports no subscriptions, entitlementsReported is false and collectives is [].

swamp subscription start

Opens the swamp-club billing page in a browser, to upgrade or manage billing for yourself or a collective. Makes no call to swamp-club of its own.

• What it opens: <server>/billing by default; <server>/o/<slug>/billing with --collective. A personal collective's page redirects to /billing. Only owners and admins can manage a collective's billing; a member is sent to the collective's page.
• Output for each case: Opening <url> in your browser.; with --no-browser, Manage billing at <url>; when no browser can be opened (for example over SSH or on a headless machine), Could not open a browser. Open this URL to manage billing: followed by the URL. All three exit 0.
• Signed out in the browser: the billing page asks the user to sign in, then returns to it.
• SWAMP_CLUB_URL: opens that server's billing page.
• --json: { "url": …, "opened": true|false, "collective": "<slug>"|null }; opened is false for --no-browser and when no browser could be opened.
• Plans are bought, changed and cancelled on the web page; the CLI only opens it. A Personal License is taken from the same page.

Links

• Link the new page from content/manual/reference/swamp-account-requirement.md where it fits naturally (for example where it discusses what an account gives you), without restructuring that page.
• Check the manual's reference index or navigation picks up the new page (pick an order that sits beside issue-commands.md and invite-commands.md).

Acceptance

• content/manual/reference/subscription-commands.md exists, follows the reference-page conventions, and covers both subcommands, every flag, the standings table, the call-to-action rule, the older-server case, SWAMP_CLUB_URL, and both --json documents
• Every example matches the shipped CLI output byte for byte (check against swamp subscription status, status --json, start --no-browser and start --no-browser --json on a current build)
• The page is linked from at least one existing manual page and appears in the manual's navigation
• No other manual page changes beyond the link

Out of scope

• swamp-uat tests for swamp subscription (a separate issue)
• The inbox (slice 2)
• Changes to the bundled swamp skill