[George-Payne]

AI-3606 (no GitHub issue)

What & why

Creating a workspace from kcap setup always provisioned Free, so neither the terminal wizard nor the agent-led install at kurrent.io/install could offer the 30-day Team trial that kcap-web already supports. Setup now takes --tier team|free alongside --org/--slug, and the interactive create flow asks for a plan with the Team trial first.

Where to look

The fallback in SpectreTenantProvisioner.ProvisionAsync. kcap-web refuses a trial for a personal email (400 work_email_required) or a domain that has had one (409 trial_exists), both before it reserves anything, so setup re-requests on Free and says why instead of ending a run whose sign-in is already approved. Without --tier, a scripted run stays on Free, so no script starts a time-limited trial it never asked for.

free_limit and flagged now get their own messages; the fallback can reach free_limit, which otherwise reads as a taken slug.

Verification

TenantProvisionerHeadlessTests 23/23, SetupCommandTests/ParseRequestedWorkspace* 19/19, TenantProvisioningClientTests 12/12, ProvisioningWireTests 6/6, run in the devcontainer.

Summary by CodeRabbit

• New Features

  • Workspace setup now offers a 30-day Team trial, with Free available as the default or as an explicit choice.
  • Interactive and unattended setup support selecting a workspace tier. If a Team trial is unavailable, setup creates a Free workspace and explains why.
  • Confirmation and retry guidance now reflect the selected tier.

• Documentation

  • Updated setup help and examples to explain tier selection, defaults, and trial eligibility.

[linear-code]

AI-3606

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: d8d46b01-cbc0-4d95-95ea-7c26eec8d644

---

📥 Commits

Reviewing files that changed from the base of the PR and between 53d6372 and bdecd2b.

---

📒 Files selected for processing (12)

• README.md
• src/Capacitor.App/Services/Onboarding/WizardAuthBridges.cs
• src/Capacitor.Cli.Core/Auth/OAuthLoginFlow.cs
• src/Capacitor.Cli.Core/Auth/TenantProvisioningClient.cs
• src/Capacitor.Cli.Core/Auth/WorkspaceTier.cs
• src/Capacitor.Cli.Core/Resources/help-setup.txt
• src/Capacitor.Cli/Commands/RequestedWorkspace.cs
• src/Capacitor.Cli/Commands/SetupCommand.cs
• src/Capacitor.Cli/Commands/SpectreTenantProvisioner.cs
• test/Capacitor.Cli.Core.Tests.Unit/Auth/TenantProvisioningClientTests.cs
• test/Capacitor.Cli.Tests.Unit/Commands/SetupCommandTests.cs
• test/Capacitor.Cli.Tests.Unit/Commands/TenantProvisionerHeadlessTests.cs

---

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• kurrent-io/kcap-server (auto-detected)
• kurrent-io/skills (auto-detected)

---

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.

---

---

📝 Walkthrough

Walkthrough

Workspace setup now supports Team and Free tiers. The CLI accepts a tier option, sends the selected tier in provisioning requests, and retries eligible Team trial refusals on Free.

Changes

Workspace tier provisioning

Layer / File(s)	Summary
Tier contract and request serialization src/Capacitor.Cli.Core/Auth/WorkspaceTier.cs, src/Capacitor.Cli.Core/Auth/TenantProvisioningClient.cs, src/Capacitor.App/Services/Onboarding/WizardAuthBridges.cs, test/Capacitor.Cli.Core.Tests.Unit/Auth/TenantProvisioningClientTests.cs	Adds Team and Free tier values and maps them to request wire values. Provisioning accepts the selected tier. The onboarding bridge passes Free, and tests cover serialization and existing request behavior.
Capture the requested workspace tier src/Capacitor.Cli/Commands/RequestedWorkspace.cs, src/Capacitor.Cli/Commands/SetupCommand.cs, test/Capacitor.Cli.Tests.Unit/Commands/SetupCommandTests.cs, src/Capacitor.Cli.Core/Resources/help-setup.txt, src/Capacitor.Cli.Core/Auth/OAuthLoginFlow.cs, README.md	--tier accepts team or free and defaults to Free. The parser rejects invalid or incomplete tier arguments. Setup guidance and examples describe tier selection and the Team trial.
Select a plan and handle Team trial refusals src/Capacitor.Cli/Commands/SpectreTenantProvisioner.cs, test/Capacitor.Cli.Tests.Unit/Commands/TenantProvisionerHeadlessTests.cs	Interactive setup offers Team and Free. Scripted setup uses the requested tier. A Team request retries once on Free for work_email_required or trial_exists; tests cover these refusals, other refusal responses, and tier-aware retry guidance.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant SpectreTenantProvisioner
  participant TenantProvisioningClient
  participant ProvisioningAPI
  User->>SpectreTenantProvisioner: Select Team plan
  SpectreTenantProvisioner->>TenantProvisioningClient: Provision Team tier
  TenantProvisioningClient->>ProvisioningAPI: Send Team tier request
  ProvisioningAPI-->>TenantProvisioningClient: Return work_email_required or trial_exists refusal
  TenantProvisioningClient-->>SpectreTenantProvisioner: Return refusal
  SpectreTenantProvisioner->>TenantProvisioningClient: Retry with Free tier
  TenantProvisioningClient->>ProvisioningAPI: Send Free tier request
  ProvisioningAPI-->>TenantProvisioningClient: Return provisioning result
  TenantProvisioningClient-->>SpectreTenantProvisioner: Return result

Loading

Suggested reviewers: inok, alexeyzimarev

---

Merge Risk | ⚪ Minimal · up to bdecd

Merge Risk: ⚪ Minimal · up to bdecd

No actionable merge-blocking risk is established for the workspace tier change; it is ready for normal merge checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to bdecd

Plan selection and the single Free fallback are tightly bounded and preserve existing sign-in behavior. No introduced security bypass was established. Remaining uncertainty concerns whether eligible trial refusals leave no reservation and whether the hosted service safely handles repeated or concurrent provisioning requests.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The client-visible transition concerns a signed-in account's requested workspace and canonical slug, with at most two sequential provisioning calls per invocation. This does not establish the maximum server-side provisioning exposure: tenant isolation, resource authority and concurrent-request enforcement remain unverified.

Trust Boundaries and Controls

• observed — User-selected plan data crosses the existing authenticated provisioning boundary. The client does not convert flagged, disposable-email, ownership-conflict, Free-limit or transport responses into a Free fallback; only the two exact trial-refusal pairs qualify.

Resilience and Maintainability Implications

• inferred — The fallback's ownership safety depends on the service rejecting eligible Team requests before reservation. The client asserts that contract but supplies no explicit idempotency key; its joinId is documented as correlation data. Server transaction, duplicate-request and interruption-recovery guarantees cannot be established from this client implementation.

Hardening Proposals

• proposed — Validate the receiving service's trial-refusal contract with evidence that both eligible responses precede reservation, and that repeated, concurrent and interrupted requests preserve one account-bound workspace ownership outcome. Treat this as contract assurance, not an observed security defect.

---

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 40.54% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 37 functions across 10 files. (2 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the primary change: offering the Team trial during workspace creation in setup.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

---

Full details: Docstring Coverage

Explanation

Docstring coverage is 40.54% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 37 functions across 10 files. (2 skipped: 2 unsupported.)

---

• Fix all pre-merge checks with AI

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Offer the Team trial during CLI workspace creation

✨ Enhancement 🐞 Bug fix 🧪 Tests 📝 Documentation 🕐 40+ Minutes

AI Description

• Offer the 30-day Team trial in interactive setup and through --tier team in scripted setup.
• Keep scripted setup on Free by default; retry on Free when trial eligibility is refused.
• Clarify provisioning failures and document and test the new plan choices.

Diagram

graph TD
  Interactive["Interactive wizard"] --> Tier["Tier selection"] --> Client["Provision client"] --> Web["kcap-web API"] --> Refusal{"Trial refused?"}
  Flags["Setup flags"] --> Tier
  Refusal -->|Yes| Retry["Free retry"] --> Client
  Refusal -->|No| Outcome["Provision outcome"]

Loading

High-Level Assessment

Keep the server-response-driven fallback. A separate eligibility check would require another API interaction and could disagree with the eventual provisioning decision; retrying only the two known, pre-reservation refusals preserves the existing flow without starting an unrequested trial.

Files changed (11) +213 / -37

Enhancement (6) +66 / -18

WizardAuthBridges.csKeep app wizard provisioning on Free +1/-1

Keep app wizard provisioning on Free

• Passes Free explicitly to the provisioning client so the app wizard retains its existing plan behavior after the client signature changes.

src/Capacitor.App/Services/Onboarding/WizardAuthBridges.cs

TenantProvisioningClient.csSend the requested workspace tier to provisioning +2/-2

Send the requested workspace tier to provisioning

• Accepts a workspace tier and serializes its wire value instead of always sending 'free'.

src/Capacitor.Cli.Core/Auth/TenantProvisioningClient.cs

WorkspaceTier.csDefine supported workspace plans +14/-0

Define supported workspace plans

• Adds Team and Free tier values with parsing for CLI input and conversion to provisioning API values.

src/Capacitor.Cli.Core/Auth/WorkspaceTier.cs

RequestedWorkspace.csCarry the requested plan through scripted setup +3/-3

Carry the requested plan through scripted setup

• Adds a tier to the workspace request record, defaulting to Free when no plan is supplied.

src/Capacitor.Cli/Commands/RequestedWorkspace.cs

SetupCommand.csValidate and parse the setup tier flag +10/-4

Validate and parse the setup tier flag

• Parses '--tier team|free' for workspace creation and rejects missing, unsupported, or standalone tier values. Leaves runs without '--tier' on Free.

src/Capacitor.Cli/Commands/SetupCommand.cs

SpectreTenantProvisioner.csOffer Team and recover from trial eligibility refusals +36/-8

Offer Team and recover from trial eligibility refusals

• Offers the Team trial first in interactive creation and passes the chosen tier to provisioning. Explains work-email and prior-trial refusals before retrying on Free, and gives 'flagged' and 'free_limit' distinct failure messages.

src/Capacitor.Cli/Commands/SpectreTenantProvisioner.cs

Tests (3) +133 / -12

TenantProvisioningClientTests.csVerify provisioning requests carry their tier +22/-5

Verify provisioning requests carry their tier

• Checks that Team is serialized as 'team' and updates existing client tests to request Free explicitly.

test/Capacitor.Cli.Core.Tests.Unit/Auth/TenantProvisioningClientTests.cs

SetupCommandTests.csCover setup tier parsing and validation +32/-0

Cover setup tier parsing and validation

• Tests the Free default, accepted tier values, and rejection of unsupported, missing, or standalone tier arguments.

test/Capacitor.Cli.Tests.Unit/Commands/SetupCommandTests.cs

TenantProvisionerHeadlessTests.csCover Team requests and Free fallback +79/-7

Cover Team requests and Free fallback

• Records requested tiers in the HTTP stub and tests Team propagation, both eligible fallback responses, unrelated refusals, and the 'free_limit' message.

test/Capacitor.Cli.Tests.Unit/Commands/TenantProvisionerHeadlessTests.cs

Documentation (2) +14 / -7

OAuthLoginFlow.csShow a Team trial command in non-interactive guidance +1/-1

Show a Team trial command in non-interactive guidance

• Adds '--tier team' to the suggested workspace-creation command for sessions that cannot answer setup prompts.

src/Capacitor.Cli.Core/Auth/OAuthLoginFlow.cs

help-setup.txtDocument setup plan selection and trial fallback +13/-6

Document setup plan selection and trial fallback

• Describes '--tier', its Free default, the Team trial, and the interactive plan prompt. Explains that trial-ineligible accounts receive a Free workspace instead.

src/Capacitor.Cli.Core/Resources/help-setup.txt

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (1) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. README omits the workspace plan option ✓ Resolved

Description

Setup's new --tier option is documented in the help resource but omitted from README's setup
examples and prose. Users following the README cannot discover how to request the Team trial or
understand the Free default and fallback behavior.

Code

src/Capacitor.Cli.Core/Resources/help-setup.txt[R44-49]

+  --tier <team|free>          Plan for a workspace created with --org and --slug:
+                              team starts a 30-day Team trial, free is the Free
+                              plan (the default). An account that cannot have the
+                              trial (a personal email, or a domain that already
+                              has one) gets a Free workspace instead, and setup
+                              says why.

Relevance

●●● Strong

Recent accepted findings consistently require README updates for new user-facing CLI flags and
behavior.

PR-#677
PR-#640

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The changed setup help introduces the new --tier <team|free> user-facing option and documents its
default and fallback behavior, while the existing README setup examples and prose still show only
--org and --slug without describing --tier. This violates the requirement to update README.md
for user-facing CLI flags and behavior changes.

Rule 2270057: Keep CLI documentation in README.md in sync with user-facing CLI changes
src/Capacitor.Cli.Core/Resources/help-setup.txt[44-49]
README.md[204-208]
README.md[262-262]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR adds the user-facing `kcap setup --tier <team|free>` option and changes workspace creation behavior, but README.md does not document the option, its default, or the Team-trial fallback.

## Fix Focus Areas
- src/Capacitor.Cli.Core/Resources/help-setup.txt[44-49]
- README.md[204-208]
- README.md[262-262]

## Recommended Fix
Update README.md in the Getting started and Initial setup/CLI documentation to show `--tier team|free`, explain that Free is the default, and describe the Team-trial refusal fallback consistently with the setup help text.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. The merge subject has no issue reference ✗ Dismissed

Description

The pull request title Offer the Team trial when setup creates a workspace does not end with the
required GitHub issue reference in the form (#digits). The subject is otherwise a single
imperative clause, but the missing reference prevents it from matching the required merge-subject
format.

Code

src/Capacitor.Cli.Core/Auth/WorkspaceTier.cs[R1-4]

+namespace Capacitor.Cli.Core.Auth;
+
+// The two self-serve plans kcap-web provisions. Team starts a 30-day trial; neither is billed.
+public enum WorkspaceTier { Team, Free }

Relevance

●●● Strong

Recent PR guidance accepts enforcing GitHub issue references in PR metadata and descriptions.

PR-#659

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The supplied pull request title has no trailing (#digits) reference, which fails the required
subject pattern and the 80-character single-clause subject policy.

Rule 2897961: Enforce single-clause imperative commit subject with GitHub issue reference and 80-char limit

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The merge subject does not include the required GitHub issue reference in the form `(#digits)`.

## Fix Focus Areas
- src/Capacitor.Cli.Core/Auth/WorkspaceTier.cs[1-4]

## Recommended Fix
Update the pull request title or merge commit subject to use one imperative clause followed by a real GitHub issue reference, such as `Offer the Team trial when setup creates a workspace (#123)`, and keep the full subject at 80 characters or fewer.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. A retry creates the wrong workspace plan ✓ Resolved

Description

PollAsync builds the scripted retry command without the selected --tier, even though
CreateRequestedAsync now passes that tier into provisioning. If a Team request is accepted but
polling reports failure or not-found, following the printed retry command defaults to Free and sends
"free" on the next provisioning request.

Code

src/Capacitor.Cli/Commands/SpectreTenantProvisioner.cs[152]

+        return await ProvisionAsync(want.OrgName, slug, want.Origin, want.Tier, tokens, ct);

Relevance

●●● Strong

A closely matching accepted finding required preserving workspace-creation flags in scripted retry
commands.

PR-#667

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The changed caller supplies the requested tier, but the polling failure guidance drops it; the setup
parser defaults an omitted tier to Free, which the client serializes into the request.

src/Capacitor.Cli/Commands/SpectreTenantProvisioner.cs[150-152]
src/Capacitor.Cli/Commands/SpectreTenantProvisioner.cs[269-278]
src/Capacitor.Cli/Commands/SpectreTenantProvisioner.cs[290-305]
src/Capacitor.Cli/Commands/SetupCommand.cs[2307-2314]
src/Capacitor.Cli.Core/Auth/TenantProvisioningClient.cs[43-47]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A scripted Team provisioning run prints a retry command that omits its selected plan, so following it requests Free.
## Fix Focus Areas
- src/Capacitor.Cli/Commands/SpectreTenantProvisioner.cs[199-220]
- src/Capacitor.Cli/Commands/SpectreTenantProvisioner.cs[262-305]
## Recommended Fix
Pass the effective provisioning tier into polling and include `--tier team` in scripted create-again commands when appropriate. If a Team refusal caused a Free fallback, use Free as the effective tier.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View medium (1)

4. Repeated plan flags can start a trial ✗ Dismissed

Description

ParseRequestedWorkspace takes only the first --tier value because ValuedFlag searches with
Array.IndexOf and does not check for repetitions. A command ending in --tier team --tier free
silently selects Team despite the later Free choice, so its provisioning request starts a trial.

Code

src/Capacitor.Cli/Commands/SetupCommand.cs[2307]

+        var (tierGiven, tierText) = ValuedFlag(args, "--tier");

Relevance

●●● Strong

Accepted CLI parsing precedents favor rejecting ambiguous or silently mishandled flag forms.

PR-#1005
PR-#1054

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The flag helper returns the value following the first matching token; only that value is parsed and
stored, then the requested tier is passed to provisioning.

src/Capacitor.Cli/Commands/SetupCommand.cs[2278-2288]
src/Capacitor.Cli/Commands/SetupCommand.cs[2305-2314]
src/Capacitor.Cli/Commands/SetupCommand.cs[2338-2341]
src/Capacitor.Cli/Commands/SpectreTenantProvisioner.cs[150-152]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Repeated `--tier` flags silently use the first value, even when a later value asks for Free.
## Fix Focus Areas
- src/Capacitor.Cli/Commands/SetupCommand.cs[2278-2288]
- src/Capacitor.Cli/Commands/SetupCommand.cs[2305-2314]
## Recommended Fix
Detect and reject repeated `--tier` occurrences before constructing `RequestedWorkspace`, and add a parsing test with conflicting values.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. The plan file has two primary types 📘 Rule violation ⚙ Maintainability

Description

WorkspaceTier.cs declares the public enum WorkspaceTier and the public static class
WorkspaceTiers, while the helper is not named using the rule's <EnumName>Extensions convention
and also contains the non-extension Parse method. The file therefore does not have one uniquely
named primary type, so a later reader cannot identify the file's owning type from its filename.

Code

src/Capacitor.Cli.Core/Auth/WorkspaceTier.cs[R4-7]

+public enum WorkspaceTier { Team, Free }
+
+public static class WorkspaceTiers {
+    public static string Wire(this WorkspaceTier tier) => tier == WorkspaceTier.Team ? "team" : "free";

Relevance

● Weak

Recent reviewers rejected splitting multiple public types despite the one-primary-type convention.

PR-#875
PR-#1140

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The added file defines two public top-level declarations: WorkspaceTier and WorkspaceTiers. The
second type contains both an extension method and a separate static parser, so it does not meet the
narrow enum-plus-extension-method exception as written.

Rule 3162234: One primary type per file, with only narrow documented exceptions
src/Capacitor.Cli.Core/Auth/WorkspaceTier.cs[4-12]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`WorkspaceTier.cs` contains two public top-level types, and `WorkspaceTiers` is not a narrowly conforming enum extension type because it also defines `Parse`.

## Fix Focus Areas
- src/Capacitor.Cli.Core/Auth/WorkspaceTier.cs[4-7]

## Recommended Fix
Keep `WorkspaceTier` in `WorkspaceTier.cs`; move the helper into a separate file named `WorkspaceTierExtensions.cs` if it only contains enum extensions, or rename and split the parsing functionality so each public primary type has a matching file and the allowed exception is satisfied.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

---

Context sources

✅ Compliance rules (platform): 64 rules

✅ Cross-repo context — repo relationships

  Explored: repo: kurrent-io/kcap-web (sha: cbd243e7) — View relationship

  Explored: repo: kurrent-io/cloud-meta (sha: 2c2a8b84) — View relationship

Review mode: Auto: ⚖️ Balanced: Runtime provisioning and trial logic carry contract and user-impact risks.

Tip of the day

💡 Did you know, you can commit Qodo's fix in one click with committable suggestions (GitHub & GitLab)

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗