@nebulr-group/bridge-cli 0.6.0-beta.3 → 0.6.0-beta.5

package/dist/prompts/decisions/feature-control.md

@@ -0,0 +1,105 @@
+# Feature control — decision guide
+
+Turning features on and off for some people and not others, without a deploy. The tool is a **flag**: code asks for it by key, and the flag's rule decides the answer.
+
+> Other decision guides: `bridge guide decision <name>` (MCP: resource `bridge://guides/decisions/<name>`). How the pieces work underneath: `bridge guide mechanisms`.
+
+## The rule that decides everything else
+
+- **Is a feature on for them? A flag.** Always, and for good. The flag is the stable place in code; the *reasons* live in its rule and change as the business does: 10% of users today, "plan is Pro" tomorrow, one named customer as an exception next month. Each of those is a rule edit, not new code.
+- **How much do they get? The plan.** Prices, trials and limits live on the plan: see the **payments** guide.
+- **Who inside a workspace may do it? A role.** See the **roles** guide.
+
+A plan can also grant a feature on its own (a *plan feature*, checked with `@RequireEntitlement` on the backend and `<Entitled>` in the UI; the payments guide explains it). Use that only when the feature *is* what the plan sells and nothing else will ever decide it: the backend then refuses it without extra wiring. Anything that could ever need a rollout, a trial cohort or a one-customer exception is a flag.
+
+## Start from what is there
+
+| Read | MCP | CLI |
+|---|---|---|
+| Every flag with its rule, and warnings on flags that cannot mean what they look like | `list_feature_flags` | `bridge flag list` |
+| One flag | `get_flag` | `bridge flag get <key>` |
+| Plan keys and role keys, for rules | `list_plans`, `list_roles` | `bridge plan list`, `bridge role list` |
+
+## Ask the developer
+
+Product questions. Ask, wait, never guess.
+
+1. **Which feature, in their words, and who should get it?** Everyone, nobody yet, a percentage of users, one plan, some roles, named customers, or a mix.
+2. **What do people without it see?** Nothing at all, a teaser with an upgrade link, or the old version.
+3. **Should it switch on or off by itself at a set time?**
+4. **If it is tied to a plan: is it simply part of that plan for ever,** or might it later go to a trial group or a single customer too? (This picks flag or plan feature, above.)
+
+## Decide yourself
+
+- **Flag keys in kebab-case, named after the feature: `new-editor`, `analytics`.** Reason: the key is what code reads; it should still make sense after the rollout is over.
+- **Boolean unless the developer needs variants.** Reason: on/off covers almost every case and reads plainly in code.
+- **Target a plan by its key (`pro`), from `list_plans`, never its display name,** whatever an example elsewhere shows. Reason: the app sends the key.
+- **Always give the rule an `otherwiseValue`, and make it the safe answer (usually `false`).** Reason: anyone the rule does not match gets it.
+- **Test the rule with the exact attributes the app sends before relying on it** (`evaluate_feature_flag` / `bridge flag eval`). Reason: a rule on an attribute the app never sends silently answers `otherwiseValue` for everyone.
+- **Read flags through the SDK the per-framework guide names, never with a hand-written request.** Reason: a wrong address fails into "off", which looks exactly like "not bought".
+- **Treat a warning from `list_feature_flags` as a bug to fix now.**
+
+## The attributes a rule can test
+
+These are the exact names and values. A rule on any other name matches nothing unless the app sends that attribute itself.
+
+**Sent by the browser SDKs** (SvelteKit, React, Next.js, Angular) for a signed-in person, read from their token:
+
+| Attribute | Value | Compared |
+|---|---|---|
+| `user.id` | the person's id | exactly |
+| `user.email` | their email | exactly |
+| `user.role` | the role **key** as created, e.g. `OWNER`, `ADMIN` | exactly: `admin` does not match `ADMIN` |
+| `tenant.id` | the workspace id | exactly |
+| `tenant.plan` | the plan **key**, e.g. `pro` (not the name) | ignoring case: `Pro` matches `pro` |
+| `privileges` | a list of privilege keys | as a list; target a role instead |
+
+**Also sent by the browser SDKs, from the workspace's subscription:**
+
+| Attribute | Value |
+|---|---|
+| `bridge:billing.plan` | the plan key, compared exactly |
+| `bridge:billing.subscription.status` | `trial`, `active`, `past_due`, `cancel_at_period_end` or `canceled` |
+| `bridge:billing.trial` | `true` or `false` |
+| `bridge:billing.quota.<metric>.used` / `.limit` / `.remaining` | numbers |
+| `bridge:billing.quota.<metric>.percent_used` | a fraction: `0.8` is 80% |
+| `bridge:billing.entitlement.<name>` | `true` or `false`, including `app_active` (the subscription is active, trialing, past due or cancelling) |
+
+**On the NestJS backend** only the signed-in person's id is filled in (as the identity). A rule on `tenant.plan` or `user.role` sees nothing there until the app passes those values from the verified user on each call; the NestJS flags guide shows how. Never pass values the client sent.
+
+**Percentage rollouts** bucket on the identity: the person's id when signed in, a stored anonymous id in the browser otherwise. A backend call with no signed-in person gets the default.
+
+Operators: `eq`, `neq`, `in`, `not_in`, `contains`, `not_contains`, `gt`, `lt`, `between`, `regex`, `exists`, `not_exists`.
+
+A condition's values are always a list, even for a single value.
+
+## Do it
+
+| Step | MCP | CLI |
+|---|---|---|
+| Create a flag with its rule | `create_feature_flag` | `bridge flag create --key analytics --state on-with-rule --rule '<json>'` |
+| Change a rule or values | `update_feature_flag` | `bridge flag update --key analytics --rule '<json>'` |
+| Switch it on or off for everyone now (the rule is kept, unused while on) | `toggle_feature_flag` | `bridge flag toggle --key analytics --enabled true` |
+| Check who gets what | `evaluate_feature_flag` | `bridge flag eval analytics --identity u1 --attribute tenant.plan=pro` |
+| Switch at a set time | `set_flag_schedule` | `bridge flag schedule set analytics --at … --state on` |
+| Copy flags between apps | `export_feature_flags`, `import_feature_flags` | `bridge flag export`, `bridge flag import <file>` |
+| Code for the framework | `get_integration_guide` (topic `feature-flags`) | `bridge guide flags --framework svelte` |
+
+A rule for "Pro only":
+
+```json
+{ "branches": [{ "conditions": [{ "attribute": "tenant.plan", "operator": "eq", "values": ["pro"] }], "returnValue": true }],
+  "otherwiseValue": false, "rolloutPct": 100 }
+```
+
+## Prove it
+
+1. `evaluate_feature_flag` / `bridge flag eval` with a context that should get the feature, then one that should not: the answers differ as the developer intended.
+2. `list_feature_flags` / `bridge flag list` shows no warnings on the flag.
+3. In the app, as a test user on each side of the rule.
+
+## Where this connects
+
+- **Payments:** plan keys, and plan features versus flags.
+- **Roles:** role keys for `user.role`, and why a flag is not a permission.
+- **Going live:** flags are per app; a production app needs its own (`export_feature_flags`, then `import_feature_flags`).

package/dist/prompts/decisions/going-live.md

@@ -0,0 +1,59 @@
+# Going live — decision guide
+
+Everything between "it works on my machine" and real users signing up and paying. Bridge keeps a readiness checklist for each app; this guide is how to work through it with the developer.
+
+> Other decision guides: `bridge guide decision <name>` (MCP: resource `bridge://guides/decisions/<name>`). How the pieces work underneath: `bridge guide mechanisms`.
+
+## Start from the checklist
+
+`get_setup_status` / `bridge setup status` lists every item (redirect URIs, default callback, allowed origins, UI URL, sign-in methods and provider credentials, email sender, Stripe, plans, first real sign-in) as configured, missing or needing attention, each with its next step. Its `productionNeeds` is what must still change before real users arrive: localhost addresses, test Stripe keys, an unconfirmed sender. Work from that list, not from memory.
+
+`list_apps` shows which apps this connection can reach. `diagnose_integration` / `bridge diagnose` compares the project's env files with the app they point at.
+
+## Ask the developer
+
+Product questions. Ask, wait, never guess.
+
+1. **Is the app you have been building with already serving real users?** If yes, it is the production app. If no, see "a separate production app" below.
+2. **What is the production address of the frontend** (and of the backend, if it calls Bridge)?
+3. **For each social sign-in provider: the production client id and secret,** if they use a different provider app in production.
+4. **The live Stripe keys** (`sk_live_…`, `pk_live_…`), from the Stripe account that should receive the money. Never invent, guess or reuse a key.
+5. **Which address and name should emails come from** in production?
+
+## Decide yourself
+
+- **A separate Bridge app for production** when the current one has no real users. Reason: test users, test Stripe keys and localhost addresses stay out of production, and nothing in development can touch a real customer. Create it with `create_app`; it does not become the default, so pass its id as `app` or call `use_app`. Copy flags across with `export_feature_flags` then `import_feature_flags`, and recreate each plan with `apply_plan`.
+- **Production env files carry the production app id and no base URL.** Reason: an unset base URL means Bridge's production API; a leftover stage or local base URL sends a production app id to the wrong place, and sign-in fails.
+- **Add production addresses; remove localhost ones only from the production app.** Reason: removing them from the development app breaks local work.
+- **Add redirect URIs one at a time and send allowed origins as a full list** (read first). Reason: the first keeps the list; the second replaces it.
+- **Register the production callback in every social provider's console** (`setup_sso` returns it). Reason: providers refuse callbacks they do not know.
+- **Never put a secret key in a browser variable** (`VITE_*`, `NEXT_PUBLIC_*`). Reason: everything in those ships to every visitor. `diagnose_integration` flags it.
+- **A test user on a production app needs the developer's say-so.** Reason: it creates a workspace in the app real users share; the tool refuses without confirmation.
+
+## Do it
+
+| Step | MCP | CLI |
+|---|---|---|
+| Readiness checklist | `get_setup_status` | `bridge setup status` |
+| Check a project's env files | `diagnose_integration` | `bridge diagnose` |
+| Create a production app | `create_app`, then `use_app` | — (create it in the dashboard, then `bridge auth login --app <id>`) |
+| Production URL, default callback, allowed origins | `update_app` | `bridge app update --ui-url … --default-callback-uri … --allowed-origins …` |
+| Production callback URL | `add_redirect_uri` | `bridge app redirect-uris add <url>` |
+| Live Stripe keys | `setup_payments` | `bridge setup payments --stripe-key sk_live_… --stripe-public-key pk_live_…` |
+| Email sender | `setup_communication` | `bridge setup communication --from-address … --from-name …` |
+| Copy flags | `export_feature_flags`, `import_feature_flags` | `bridge flag export --out flags.json`, `bridge flag import flags.json` |
+| Copy a plan | `apply_plan` | `bridge plan apply --spec @plan.json` |
+
+## Prove it
+
+1. `get_setup_status` / `bridge setup status` again: show the developer what is left. Nothing in `productionNeeds` should be a surprise to them.
+2. With the developer's agreement, `create_test_user` then `verify_login` (`bridge test-user create --confirm "<app name>"`, then `bridge test-user verify`) against the production app: a real sign-in from the production origin.
+3. `get_stripe_status` / `bridge stripe status`: live keys, webhook working.
+4. The first real sign-in appears on the checklist once someone signs up.
+
+## Where this connects
+
+- **Login:** redirect URIs, origins and provider credentials.
+- **Payments:** live keys, and plans on the production app.
+- **Feature control:** flags are per app.
+- **Look and feel:** a confirmed sender address.

package/dist/prompts/decisions/login.md

@@ -0,0 +1,68 @@
+# Login — decision guide
+
+How people sign up and sign in to the developer's app. This guide says what to ask, what to decide yourself, and which tool or command does each step. The code itself is in the per-framework guide.
+
+> Other decision guides: `bridge guide decision <name>` (MCP: resource `bridge://guides/decisions/<name>`). How the pieces work underneath: `bridge guide mechanisms`.
+
+## Start from what is there
+
+Read before you ask anything, so your questions are about changes, not about the current state.
+
+| Read | MCP | CLI |
+|---|---|---|
+| Sign-in methods and token lifetimes | `get_auth_config` | `bridge auth config` |
+| URLs, redirect URIs, allowed origins | `get_app` | `bridge app get` |
+| The exact env variables for this project | `get_environment_info` | — |
+
+A new app has password, magic link and passkeys on, two-factor off, and no social providers.
+
+## Ask the developer
+
+Product questions. Ask, wait, never guess.
+
+1. **Which ways should people be able to sign in?** Password is always there. Offer magic link, passkeys, Google, GitHub, Microsoft (Azure AD), LinkedIn, Facebook. Company SSO (SAML or OIDC) is set up in the Bridge dashboard, not from here.
+2. **Should two-factor sign-in be available?**
+3. **Should sign-in happen on Bridge's hosted page, or inside the app on its own address?** Both use the same one route file; the look-and-feel guide covers what each looks like.
+4. **Can anyone sign up, or only people who are invited?** This is a teams question: see the **teams** guide before changing it.
+5. **For each social provider they pick: the client id and client secret** from that provider's console. Never invent, guess or reuse a credential.
+
+## Decide yourself
+
+Apply these without asking. Say the reason in one line.
+
+- **Callback URL is `<frontend-url>/auth/oauth-callback`,** registered as a redirect URI and as the default callback. Reason: the sign-in route file serves that address, and Bridge refuses any callback it has not seen.
+- **Add redirect URIs one at a time** with `add_redirect_uri` / `bridge app redirect-uris add`. Reason: they keep the rest of the list; nothing is lost.
+- **Before changing allowed origins, read the current list and pass it back with the new origin added.** Reason: `update_app` and `bridge app update --allowed-origins` replace the whole list.
+- **Set the UI URL to the frontend's address.** Reason: links in invitation and password-reset emails are built from it; unset, people land on Bridge's hosted pages.
+- **Leave token lifetimes at their defaults** unless the developer raises it. Reason: the defaults are safe. There are no password-complexity rules to set; if asked, say so.
+- **Write no sign-in pages by hand, and no token fetch helper.** Reason: the plugin serves every sign-in page (login, signup, callback, set password, forgot password, magic link, passkey setup, workspace selection) from one file.
+- **Protect every route by default; make only `/auth/*` public.** Reason: a new page is private until someone decides otherwise.
+
+## Do it
+
+| Step | MCP | CLI |
+|---|---|---|
+| Turn magic link, passkeys or two-factor on or off | `update_auth_methods` | `bridge app update --magic-link-enabled true` (also `--passkeys-enabled`, `--mfa-enabled`) |
+| Add a social provider with its credentials | `setup_sso` | `bridge setup sso --provider google --client-id … --client-secret …` |
+| Register the callback URL | `add_redirect_uri` | `bridge app redirect-uris add <url>` |
+| Set UI URL, default callback, allowed origins | `update_app` | `bridge app update --ui-url … --default-callback-uri … --allowed-origins …` |
+| Change token lifetimes (seconds) | `update_password_policy` | `bridge auth password-policy --access-token-ttl 900` |
+| Code for the framework | `get_integration_guide` (topic `auth`) | `bridge guide svelte` (hosted) or `bridge guide svelte sdk-auth` (in-app) |
+
+`setup_sso` returns a callback URL. The developer must paste it into the provider's console, or that provider's sign-in fails with a redirect mismatch. Always show it to them with that instruction. `update_auth_methods` can switch a provider on but never saves its credentials.
+
+## Prove it
+
+Do not say "it should work". Show it working.
+
+1. `diagnose_integration` / `bridge diagnose`: compares the project's env files with the real app and names every difference with its fix.
+2. `create_test_user`, then `verify_login` / `bridge test-user create`, then `bridge test-user verify`: a real sign-in, with the token checked.
+3. If sign-in works there but not in the app, the app code is the difference.
+4. When a real person cannot sign in: `debug_auth_issue` / `bridge event auth-attempts --user <email>` gives each failed attempt with its reason and fix.
+
+## Where this connects
+
+- **Teams:** who can sign up, and whether they create a workspace or join one.
+- **Roles:** what a person can do once signed in.
+- **Look and feel:** hosted or in-app sign-in, and how the pages look.
+- **Going live:** production URLs and redirect URIs replace the localhost ones.

package/dist/prompts/decisions/look-and-feel.md

@@ -0,0 +1,62 @@
+# Look and feel — decision guide
+
+How Bridge's pages and emails look to the developer's users: the sign-in pages, the subscription pages, and the emails Bridge sends in the app's name.
+
+> Other decision guides: `bridge guide decision <name>` (MCP: resource `bridge://guides/decisions/<name>`). The customisation levels in full, with every design token: `bridge guide mechanisms`.
+
+## Two places pages can live
+
+- **Hosted:** Bridge serves sign-in on its own address. Styled with the app's **branding** (colours, font, corner radius), which Bridge stores.
+- **In the app:** the same pages render inside the developer's own layout, on their address. Styled with CSS design tokens (`--bridge-*`) in the app's own stylesheet.
+
+Both use the same single route file; one setting switches sign-in into the app (`loginRoute: '/auth/login'` in SvelteKit's `bridgeBootstrap()`). Subscription pages always render in the app.
+
+## Start from what is there
+
+| Read | MCP | CLI |
+|---|---|---|
+| Hosted-page branding | `get_branding` | `bridge branding get` |
+| App name, and the email sender | `get_app` | `bridge app get` |
+
+## Ask the developer
+
+Product questions. Ask, wait, never guess.
+
+1. **Should sign-in look like part of the app, on the app's own address, or is Bridge's hosted page fine?**
+2. **What are the brand colours and font?** Ask for exact values or point at their existing stylesheet; do not pick colours for them.
+3. **What name should users see** on sign-in pages and in emails?
+4. **Which address and sender name should emails come from?** (Invitations, password resets, magic links.)
+5. **Beyond colours, should sign-in pages say anything of their own?** A different heading, a frame around the form, a page they design themselves.
+
+## Decide yourself
+
+Climb only as far as the answers require, and say which level you stopped at.
+
+- **Level 0, nothing:** in-app pages already sit inside the app's layout, so its header and navigation surround them. Reason: often this alone is enough.
+- **Level 1, tokens:** set `--bridge-primary`, `--bridge-border-radius` and friends on `:root`. Reason: tokens are the supported contract; ordinary CSS already wins over Bridge's defaults, so there is never a need for `!important`.
+- **Level 2, frame and heading:** pass the `frame` and `heading` snippets to the sign-in routes component. Reason: it changes every page at once and keeps each page's own sub-steps.
+- **Level 3, take over one page:** create that page's own route file (e.g. `src/routes/auth/login/+page.svelte`); every other page keeps working.
+- **Level 4, headless:** build everything on `getBridgeAuth()`. Only when the developer asks for it.
+- **Never copy Bridge's components into the app to restyle them.** Reason: the copy stops receiving fixes.
+- **When both hosted pages and in-app pages are used, give them the same colours.** Reason: a person moving between them should not notice.
+- **A new sender address must be confirmed.** Bridge emails that address a link; until it is clicked, mail keeps coming from Bridge's default sender. Tell the developer to look for it.
+
+## Do it
+
+| Step | MCP | CLI |
+|---|---|---|
+| Hosted-page colours, font, corners | `update_branding` | `bridge branding update --primary-btn-bg '#1a1a2e' --font-family Inter` |
+| Name users see | `update_app` (`name`) | `bridge app update --name "Acme"` |
+| Email sender | `setup_communication` | `bridge setup communication --from-address no-reply@acme.com --from-name Acme` |
+| In-app pages, tokens, snippets | `get_integration_guide` (topic `branding`, then `auth`) | `bridge guide svelte branding`, `bridge guide mechanisms` |
+
+## Prove it
+
+1. Open the sign-in page and the subscription page in the running app (or the hosted page): colours and font match what the developer gave.
+2. Trigger a password reset for a test user: the email arrives from the agreed sender, in the app's name, and its link opens the app, not a Bridge page.
+
+## Where this connects
+
+- **Login:** hosted or in-app sign-in is the same switch.
+- **Payments:** the subscription and plan-choice pages use the same tokens.
+- **Going live:** a verified sender address before real users arrive.

package/dist/prompts/decisions/payments.md

@@ -0,0 +1,81 @@
+# Payments and plans — decision guide
+
+What customers pay, what each plan includes, and what happens when they reach a limit. A **plan** belongs to a workspace, not to a person. It carries the price, the trial and the limits ("3 projects on Free, 50 on Pro"). Payments run through the developer's own Stripe account.
+
+> Other decision guides: `bridge guide decision <name>` (MCP: resource `bridge://guides/decisions/<name>`). The full model behind limits and upgrade prompts: `bridge guide mechanisms`.
+
+## Start from what is there
+
+| Read | MCP | CLI |
+|---|---|---|
+| Plans with prices and limits | `list_plans` | `bridge plan list` |
+| Every metric the plans already limit, with its kind | `list_plan_quotas` | `bridge plan quota list` |
+| Whether Stripe is connected and its webhook works | `get_stripe_status` | `bridge stripe status` |
+| Whether new customers must pick a plan first (`paymentsAutoRedirect`) | `get_app` | `bridge app get` |
+
+## Ask the developer
+
+Product questions. Ask, wait, never guess. Then show the answer back as tables (plans, prices, limits) and create nothing until the developer confirms them.
+
+1. **Which plans, and what are they called?** Is there a free one?
+2. **What does each paid plan cost, in which currency, and monthly, yearly or both?**
+3. **Is there a free trial, and how many days?**
+4. **What does each plan limit, and how much?** In their words: "2 tickets on Free, 100 on Pro", "10 seats", "1,000 exports a month".
+5. **For each limit: at the limit, block, or keep going and charge per extra unit?** If they charge, how much per unit?
+6. **Which features are only on some plans?** ("Analytics on Pro only.")
+7. **Do they want a welcome page for new customers** where they choose a plan? Offer it; create it only if they say yes.
+
+## Decide yourself
+
+- **Plan keys short and lower-case: `free`, `pro`, `team`.** Reason: the key is permanent and is what code, flag rules and tokens use; the name can change any time.
+- **Monthly and yearly prices of one tier are one plan with two prices,** never `pro-monthly` and `pro-yearly`. Reason: the subscription page then shows one plan with a monthly/yearly switch.
+- **A free plan gets a price of 0.** Reason: a plan with no price cannot be assigned to a workspace.
+- **Counter or gauge?** If deleting it frees room, it's a gauge and your app counts it; if it happened, it's a counter and Bridge counts it. Exports, AI completions and emails are counters (reset each billing period). Tickets, projects and stored files are gauges (never reset). Decide from that sentence and say which you chose.
+- **Seats are the built-in `users` metric, a gauge.** Reason: Bridge counts workspace members itself.
+- **Reuse metric names the app already has** (`list_plan_quotas`) before inventing new ones. Reason: two names for one thing split the count.
+- **Connect Stripe with test keys first; live keys only when going live.** Reason: nobody is charged while you build. Use `setup_payments` / `bridge setup payments`: it stores the keys and switches payments on in one step.
+- **Connect Stripe before adding paid prices.** Reason: each price is created in Stripe as it is saved.
+- **Leave "customers must pick a plan" on** (it is on by default) unless the developer says otherwise. Reason: a new workspace then always has a plan, so every limit and feature check has something to read.
+- **One plan, one call:** `apply_plan` / `bridge plan apply` sets name, trial, prices and limits together. Reason: a plan is never left half set up.
+
+## How a hard limit is enforced, end to end
+
+Tell the developer this plainly; it is where integrations go wrong.
+
+1. **The plan holds the number.** A limit is a quota on the plan: metric, limit, `hard`, and `counter` or `gauge`.
+2. **The backend enforces it, and only the backend.** In NestJS one decorator on the handler that creates the thing: `@RequireQuota('exports')`. Before the handler runs, a workspace at its limit gets `402` with `{ code: 'QUOTA_EXCEEDED', metric, used, limit, fix }` and the handler never runs. After a `2xx` answer, Bridge records one use. Nothing else to wire: no usage call, no counter table. If Bridge cannot answer, the request is refused with `503`, never let through.
+3. **Gauges send the app's own count.** `@RequireQuota('tickets', { current })` on create and `@SyncQuota('tickets', { current })` on delete, where `current` returns the app's count from its own database. There is no decrement.
+4. **Seats need no count at all.** `@RequireQuota('users')` on the invite handler checks the seat limit.
+5. **The frontend only explains the refusal.** With no code at all, the upgrade dialog opens on a `402`, names the limit, and links to the subscription page. A member who cannot manage billing is told to ask the owner. Disabling a button before the click (`<QuotaGate>`) or showing "8 of 10" (`useQuota`) is optional.
+6. **A frontend alone cannot enforce a limit.** Anyone can call the API directly. An app with no backend can report usage from the browser, but that is self-reported: Bridge counts what the client says.
+7. **`metered` never blocks.** Past the included amount it bills per unit through Stripe.
+8. **A plan feature is a hard limit nothing counts.** `analytics` with limit 1 on `pro` makes `@RequireEntitlement('analytics')` and `<Entitled to="analytics">` true on Pro and false elsewhere. Never put `@RequireEntitlement` and `@RequireQuota` on the same name: at the cap the entitlement answers `403` first and the upgrade dialog never opens.
+9. **The plan-choice page** (`/subscription/plan`) appears only when the app has plans and "customers must pick a plan" is on. Turn it off with `update_app` (`paymentsAutoRedirect: false`) / `bridge app update --payments-auto-redirect false`.
+
+Whether a paid feature is a plan feature or a flag with a plan rule is decided in the **feature-control** guide.
+
+## Do it
+
+| Step | MCP | CLI |
+|---|---|---|
+| Connect Stripe (keys from the developer) | `setup_payments` | `bridge setup payments --stripe-key sk_test_… --stripe-public-key pk_test_…` |
+| Set up or reshape one plan in one call | `apply_plan` | `bridge plan apply --spec @plan.json` |
+| Or step by step: create a plan with its first price | `create_plan` | `bridge plan create --key pro --name Pro --amount 29 --interval month` |
+| Add another price | `set_plan_price` | `bridge plan price set pro --amount 290 --interval year` |
+| Add a limit | `set_plan_quota` | `bridge plan quota set pro --metric tickets --limit 100 --policy hard --kind gauge` |
+| Turn off the forced plan choice | `update_app` | `bridge app update --payments-auto-redirect false` |
+| Code for the framework | `get_integration_guide` (topic `billing`) | `bridge guide billing --framework svelte`, `bridge guide billing --framework nestjs` |
+
+## Prove it
+
+1. `list_plans` / `bridge plan list` matches the tables the developer confirmed; a plan with monthly and yearly pricing is one plan.
+2. `get_stripe_status` / `bridge stripe status`: connected, webhook working.
+3. At the limit, send the decorated request with curl: it answers `402 QUOTA_EXCEEDED`. In the app, the upgrade dialog opens and names the limit.
+4. A paid plan opens Stripe Checkout and returns to the subscription page with the new plan.
+
+## Where this connects
+
+- **Feature control:** features that depend on the plan.
+- **Teams:** seats, and the plan belonging to the workspace.
+- **Roles:** who may change the plan.
+- **Going live:** live Stripe keys.

package/dist/prompts/decisions/roles.md

@@ -0,0 +1,72 @@
+# Roles and permissions — decision guide
+
+Who may do what inside a customer's workspace. A **role** (Owner, Admin, Editor…) is a named bundle of **privileges** (`USER_WRITE`, `INVOICE_APPROVE`…). Every signed-in person has one role per workspace, and their token carries its role key and privileges, so the backend can check them on every request.
+
+> Other decision guides: `bridge guide decision <name>` (MCP: resource `bridge://guides/decisions/<name>`). How the pieces work underneath: `bridge guide mechanisms`.
+
+## Which tool answers which question
+
+Three different questions, three different tools. Keep them apart.
+
+| The question | Answered by | Guide |
+|---|---|---|
+| Who, inside a workspace, may do this? | a **role** and its privileges | this one |
+| Is this feature on for them at all? | a **flag** | feature-control |
+| How much do they get (projects, seats, exports)? | the **plan** | payments |
+
+A role never stands in for a plan ("Pro users are Admins") and a plan never stands in for a role.
+
+## Start from what is there
+
+| Read | MCP | CLI |
+|---|---|---|
+| Roles, their privileges, and which is the default | `list_roles` | `bridge role list` |
+| One role in full | `get_role` | — |
+| Privileges that exist | `list_roles` (the `privileges` map) | `bridge privilege list` |
+
+A new app has two roles: **Owner** (`OWNER`, everything, including permanent deletes) and **Admin** (`ADMIN`, manage people, read workspace settings). **Owner is the default role**, which means anyone invited without a role becomes an Owner.
+
+## Ask the developer
+
+Product questions. Ask, wait, never guess.
+
+1. **What kinds of people use one customer's workspace?** For example: the person who pays, people who manage the team, people who do the work, people who only look.
+2. **For each kind, what may they do that others may not?** Ask in the app's own verbs: approve an invoice, delete a project, invite a colleague, change billing.
+3. **Which role should a newly invited person get?** Owner is rarely the right answer.
+4. **Who may manage the subscription and billing?**
+
+## Decide yourself
+
+- **Name privileges after actions, in capitals: `PROJECT_DELETE`, `INVOICE_APPROVE`.** Reason: they read like the existing ones (`USER_READ`, `TENANT_WRITE`) and say exactly what they allow.
+- **Role keys in capitals too: `EDITOR`, `VIEWER`.** Reason: the token carries the key exactly as written, and a flag rule on `user.role` compares it case for case.
+- **In code, check a privilege, not a role name.** Reason: roles get reshaped as the product grows; the privilege on a handler stays true.
+- **Keep Owner as the one role with everything.** Never strip it: it is the only role that can delete, and every workspace needs someone who can.
+- **Make the lowest sensible role the default** by creating it with the default setting on. Reason: a forgotten role on an invitation then gives too little, not too much.
+- **When changing a role's privileges, send the full list.** Reason: the update replaces the list, and anything left out is revoked.
+- **Enforce on the backend; hide buttons in the frontend only as a courtesy.** Reason: anyone can call the API directly.
+
+## Do it
+
+| Step | MCP | CLI |
+|---|---|---|
+| Add a privilege | — | `bridge privilege create --key PROJECT_DELETE --description …` |
+| Create a role | `create_role` | `bridge role create --key EDITOR --name Editor --privileges PROJECT_READ,PROJECT_WRITE` |
+| Create it as the new default | `create_role` (`isDefault: true`) | `bridge role create --key MEMBER --name Member --privileges … --is-default` |
+| Change a role's privileges | `update_role` (full list) | `bridge role update --key EDITOR --privileges …` (full list) |
+| Give a person a role | `update_user` | `bridge user update --email … --role EDITOR --tenant-id …` |
+| Code for the framework | `get_integration_guide` (topic `team`) | `bridge guide nestjs` (backend checks), `bridge guide svelte team` |
+
+On the NestJS backend the check is a decorator on the handler: `@RequirePrivilege('PROJECT_DELETE')`, or `@RequireRole('ADMIN')` when the developer really means a role.
+
+Setting the default on one role clears it from the previous default.
+
+## Prove it
+
+1. `list_roles` / `bridge role list` shows each role with exactly the privileges agreed, and the default where the developer wanted it.
+2. Call a protected backend route as a user whose role lacks the privilege: it must answer 403. Then with one who has it: it must succeed.
+
+## Where this connects
+
+- **Teams:** the role an invited person gets.
+- **Feature control:** a flag can target `user.role`, but "may this person do it" is still a privilege check on the backend.
+- **Payments:** who may change the plan.

package/dist/prompts/decisions/teams.md

@@ -0,0 +1,56 @@
+# Teams and workspaces — decision guide
+
+How customers are grouped in the developer's app. In Bridge every signed-in person belongs to a **workspace** (the API and the CLI call it a tenant). A workspace is one customer: it holds the people, their roles, and the plan the customer pays for.
+
+> Other decision guides: `bridge guide decision <name>` (MCP: resource `bridge://guides/decisions/<name>`). How the pieces work underneath: `bridge guide mechanisms`.
+
+## Start from what is there
+
+| Read | MCP | CLI |
+|---|---|---|
+| Whether people can create their own workspace (`tenantSelfSignup`) | `get_app` | `bridge app get` |
+| Existing workspaces | `list_tenants` | `bridge tenant list` |
+| The people in one workspace | `list_users` | `bridge user list --tenant-id <id>` |
+| Roles an invited person can get | `list_roles` | `bridge role list` |
+
+## Ask the developer
+
+Product questions. Ask, wait, never guess.
+
+1. **Is the app for single people or for teams?** With teams, a customer invites colleagues into a shared workspace. For single people, each person simply has a workspace of their own and never sees the word.
+2. **How does someone get in the first time?** Either they sign up and get a new workspace of their own, or they can only join by invitation from someone already inside.
+3. **When someone is invited, which role should they get?** See the **roles** guide: on a new app the default role is Owner, so an invitee without a role becomes an Owner.
+4. **Does the number of people per workspace depend on the plan?** ("1 user on Free, 10 on Pro.") If yes, that is a seat limit: see the **payments** guide.
+5. **Can one person belong to several workspaces?** Bridge supports it and shows a workspace picker at sign-in; the question is whether the developer wants to offer it in their product.
+
+## Decide yourself
+
+- **Self-signup on for a product people try on their own; off for invitation-only products.** Take it from the answer to question 2 and set `tenantSelfSignup` to match. Reason: with it off, a stranger who signs up has nowhere to land.
+- **Use Bridge's team panel for inviting and managing people** (`TeamManagementPanel` in SvelteKit) rather than a page of your own. Reason: it already handles invitations, role changes and removal against the right permissions.
+- **Seats are the built-in `users` limit.** Reason: Bridge counts workspace members itself, so there is nothing for the app to count or report.
+- **Never create workspaces from the app's own code for sign-ups.** Reason: Bridge creates one at signup when self-signup is on; creating them elsewhere makes duplicates.
+- **Create workspaces by hand only for setup and support** (an existing customer you are migrating, or a demo).
+
+## Do it
+
+| Step | MCP | CLI |
+|---|---|---|
+| Allow or stop self-signup | `update_app` (`tenantSelfSignup`) | `bridge app update --tenant-self-signup true` |
+| Create a workspace by hand | `create_tenant` | `bridge tenant create --name … --owner-email …` |
+| Invite someone into a workspace | `invite_user` | `bridge user invite --email … --role … --tenant-id …` |
+| Change someone's role | `update_user` | `bridge user update --email … --role … --tenant-id …` |
+| Limit seats per plan | `set_plan_quota` (metric `users`, kind `gauge`) | `bridge plan quota set pro --metric users --limit 10 --policy hard --kind gauge` |
+| Code for the framework | `get_integration_guide` (topic `team`) | `bridge guide svelte team` |
+
+Pass a role key on every invitation you make on the developer's behalf; leaving it out gives the app's default role.
+
+## Prove it
+
+1. Create a test user (`create_test_user` / `bridge test-user create`) and sign in (`verify_login` / `bridge test-user verify`): the response names the workspace.
+2. Invite a second address into that workspace and check it appears in `list_users` / `bridge user list` with the role you meant.
+
+## Where this connects
+
+- **Roles:** what each person in a workspace may do.
+- **Payments:** a plan belongs to the workspace, not to a person; seats are a plan limit.
+- **Login:** whether sign-up is open at all.

package/dist/prompts/mcp-tools.json

@@ -0,0 +1,78 @@
+{
+  "_comment": [
+    "The names of the Bridge MCP server's tools, and nothing else. The bundled guides are tested against this list: a guide that names a tool not in it fails src/__tests__/guide-decisions.test.ts.",
+    "Source: the `bridgeTools` registry in bridge-api, microservices/account/nebulr-api/mcp/tools/register.ts.",
+    "Generated, never edited by hand: in bridge-api run `bun scripts/generate-mcp-tools-json.ts > <bridge-cli>/bridge-cli/prompts/mcp-tools.json` (in the bridge-api container).",
+    "The count must equal the number of entries in `bridgeTools` (67 at the source below). bridge-api's guide-currency.spec.ts fails when this file and the registry disagree."
+  ],
+  "source": "bridge-api feature/mcp-journey 26792b4",
+  "tools": [
+    "add_redirect_uri",
+    "apply_plan",
+    "clear_flag_schedule",
+    "connect_stripe",
+    "create_api_token",
+    "create_app",
+    "create_feature_flag",
+    "create_plan",
+    "create_role",
+    "create_tenant",
+    "create_test_user",
+    "debug_auth_issue",
+    "delete_feature_flag",
+    "delete_tenant",
+    "diagnose_integration",
+    "evaluate_feature_flag",
+    "export_feature_flags",
+    "get_app",
+    "get_auth_config",
+    "get_branding",
+    "get_environment_info",
+    "get_flag",
+    "get_integration_guide",
+    "get_plan",
+    "get_role",
+    "get_server_info",
+    "get_setup_status",
+    "get_started",
+    "get_stripe_status",
+    "get_tenant",
+    "get_user",
+    "import_feature_flags",
+    "invite_user",
+    "list_api_tokens",
+    "list_apps",
+    "list_events",
+    "list_feature_flags",
+    "list_plan_quotas",
+    "list_plans",
+    "list_redirect_uris",
+    "list_roles",
+    "list_tenants",
+    "list_users",
+    "remove_plan_price",
+    "remove_plan_quota",
+    "remove_redirect_uri",
+    "remove_user",
+    "revoke_api_token",
+    "scaffold_flags_integration",
+    "set_flag_schedule",
+    "set_plan_price",
+    "set_plan_quota",
+    "setup_communication",
+    "setup_payments",
+    "setup_sso",
+    "toggle_feature_flag",
+    "update_app",
+    "update_auth_methods",
+    "update_branding",
+    "update_feature_flag",
+    "update_password_policy",
+    "update_plan",
+    "update_role",
+    "update_tenant",
+    "update_user",
+    "use_app",
+    "verify_login"
+  ]
+}

package/dist/prompts/orientation.md

@@ -0,0 +1,40 @@
+# What Bridge does
+
+Relay this to the developer as it stands, then add one sentence about what their app has today (read it first: `get_app` and `get_setup_status`, or `bridge app get` and `bridge setup status`).
+
+---
+
+Bridge runs everything between signup and invoice for your app, so you don't build it yourself.
+
+- **Login.** People sign up and sign in with a password, a magic link, a passkey, Google, GitHub and other providers, or their company's SSO, with optional two-factor. Bridge serves the pages; your app adds about fifteen lines. *Want to choose how people sign in?*
+- **Teams and workspaces.** Each customer gets a workspace and can invite teammates into it. You decide whether people create their own workspace or join by invitation. *Is your app for single users or for teams?*
+- **Roles and permissions.** Inside a workspace, roles decide who may do what, and your backend checks them on every request. *Who are the different kinds of people in a customer's workspace?*
+- **Payments and plans.** Plans with prices, trials and limits ("3 projects on Free, 50 on Pro"), checkout through your own Stripe account, and an upgrade prompt when someone hits a limit. *Want to set up a free tier and a paid plan?*
+- **Feature control.** Turn any feature on or off for everyone, a percentage of users, one plan or one customer, without a deploy. *Is there a feature you want to roll out carefully or sell on a higher plan?*
+- **Look and feel.** Sign-in and subscription pages in your colours and fonts, inside your own layout, and emails sent in your app's name. *Want the sign-in pages to look like the rest of your app?*
+- **Going live.** A readiness checklist that says exactly what still points at localhost or test keys, and a test sign-in that proves login works end to end. *Ready to check what stands between you and real users?*
+
+---
+
+## Where to go next
+
+Each area has a decision guide: the questions to ask the developer, and the defaults to apply without asking.
+
+| Area | Decision guide | Journey |
+|---|---|---|
+| Login | `bridge guide decision login` | `bridge guide add-login` |
+| Teams and workspaces | `bridge guide decision teams` | `bridge guide add-teams` |
+| Roles and permissions | `bridge guide decision roles` | — |
+| Payments and plans | `bridge guide decision payments` | `bridge guide add-paid-plan` |
+| Feature control | `bridge guide decision feature-control` | `bridge guide add-feature-flag` |
+| Look and feel | `bridge guide decision look-and-feel` | — |
+| Going live | `bridge guide decision going-live` | `bridge guide go-live` |
+
+In an MCP client the same guides are the resources `bridge://guides/decisions/<area>` (areas: `login`, `teams`, `roles`, `payments`, `feature-control`, `look-and-feel`, `going-live`), and the journeys are the server's prompts of the same names.
+
+How limits, upgrade prompts and page customisation actually work, for every area: `bridge guide mechanisms`.
+
+Two rules hold in every guide:
+
+1. **Product questions go to the developer.** What to charge, who may do what, what a plan includes, what users see: ask, and wait for the answer. Never guess them.
+2. **Mechanics you decide.** Where a guide gives a default, apply it and say why in one line. The developer can overrule it.