Conversation
Add a third top-level sidebar tab to the dev docs, covering ricochet Cloud at cloud.ricochet.rs. - Add a quickstart covering sign-in, organization creation, instance provisioning, and the handoff to the CLI. - Document organizations, members and roles, and per-organization single sign-on. - Document instance creation, versions and upgrades, custom domains, per-member access, and the lifecycle statuses. - Document the trial, the metered Apps and Compute Pool selection, and statements and payment. - Document the organization audit log and its CSV and JSON exports. - Link the Cloud quickstart from the dev landing page. Cover only what a customer can do. The platform-admin console is out of scope.
Distinguish the self-hosted documentation from the new Cloud tab, in dev and in 0.18. Older versions keep the Admin label as frozen snapshots of what shipped. Only the sidebar label changes, so every /admin/ URL stays valid.
|
Surge PR preview deployment succeeded. View it at https://ricochet-rs-docs-pr-344.surge.sh |
Name the tab after what it covers rather than after who reads it, so it sits beside Self-Host and Cloud as one of three deployment-agnostic sections. Rename in dev and in 0.18. Older versions keep the User label as frozen snapshots. Only the sidebar label changes, so every /user/ URL stays valid.
pat-s
changed the title
Match the wording the marketing site already uses in its footer, and keep the label a noun phrase like the Usage and Cloud tabs beside it.
Widen the sidebar to 22rem. The sidebar tabs share it in equal columns, so at the previous 18.75rem each column was 73px while "Self-Hosted" needs 79px, and the label broke at its hyphen onto a second line. Keep the labels on one line as well, so a hyphenated label can never split even if a future label outgrows its column.
Dependency management describes what happens on every deploy, and user roles describe what each role can do inside any instance. Both apply whether the instance is self-hosted or on ricochet Cloud, so neither belongs behind the Self-Hosted tab. Leave the `default_role` knob in the configuration docs and link to it, the way deployment retention already splits between the two tabs. Audit logging, cookies, package repositories and deployment retention stay put: each documents a file path or a config key that only a self-hoster can reach.
Return the sidebar to Starlight's 18.75rem default. Widening it to 22rem treated the symptom: the tabs split the sidebar into equal columns, so the short labels carried wide empty margins while "Self-Hosted" was still too narrow and broke at its hyphen. Size each tab to its own label instead and left-align the row, which fits all three side by side at the default width and lines the tabs up with the group headings below them. The row already carries no rule of its own, only an underline on the active tab, so nothing depended on the columns being equal.
Sizing each tab to its label left the hover and active backgrounds hugging the text. Space the tabs with their own inline padding instead of a gap between them, so a background reaches the neighbouring tab. Use the same inset as the sidebar links below, which keeps the first tab's label on their left edge.
Left-aligning the row left all the slack on one side, so the tabs sat off-centre in the sidebar. Centre them, which splits the slack evenly. Take the sidebar down from Starlight's 18.75rem default to 17.5rem while doing so. The three tabs and the longest sidebar labels both still fit on one line, and the content column gains the difference.
|
@JosiahParry After some relocations and theme tweaks I'm now happy with the new triple formed out of "Usage | Self-Hosted | Cloud". I also reduced the sidebar width and spacing looks good to me now. "Self-hosted" is now purely explaining installation and technical details for the self-hosted option, no matter if community or licensed. Still need to check the new "Cloud" content pages but LMK if you're fine with the general direction here. |
|
There's a lot of AI language in this still and needs to be gone through with afine tooth comb |
JosiahParry
left a comment
JosiahParry
left a comment
There was a problem hiding this comment.
Let's spend our time tomorrow going through what needs to be documented for the portal and putting together an outline that we can write ourselves.
Docs need to be (mostly) human written.
These docs wouldn't help me if i read them.
There was a problem hiding this comment.
this whole page is an AI smell.
I think, honestly, we don't need a whole page dedicatedd to "trial."
I think this page can be deleted
There was a problem hiding this comment.
The page covers subscriptions as a whole.
It should surely be reduced and more on point.
| ## Native SAML 2.0 | ||
|
|
||
| Configure `[auth.saml]` instead of `[auth.oidc]` and restart the instance: | ||
|
|
There was a problem hiding this comment.
this page needs to be rewritten by a human.
Metered billing.
There was a problem hiding this comment.
this page needs to get rewritten too.
THis should probably just be called "payment methods"
| ## What blocks a create | ||
|
|
||
| Provisioning requires an organization whose billing is in good standing. | ||
| A trialing or active organization can provision. | ||
| An organization that is past due, in its grace period, suspended, or cancelled cannot, and the create button explains why. | ||
|
|
||
| Instances are not a billing dimension and are never capped. | ||
| What you pay follows from the apps and Compute Pool you select in [Billing](/dev/cloud/billing/2-metered-resources/). |
This PR was still WIP state, I was going to rewrite most parts of it. Agree this needs a lot of polish first! |
pat-s
left a comment
pat-s
left a comment
There was a problem hiding this comment.
Wording most be simplified and reduced.
In general, not every little action and section must be described in full detail. Most are fully clear in terms of scope and usage.
We should mainly focus on the disputable ones or ones that appear both in cloud and the ricochet app itself, to avoid and clear confusion.
| ## Native SAML 2.0 | ||
|
|
||
| Configure `[auth.saml]` instead of `[auth.oidc]` and restart the instance: | ||
|
|
There was a problem hiding this comment.
The page covers subscriptions as a whole.
It should surely be reduced and more on point.
Remove the native SAML sections from the self-hosted and instance authentication pages so they can land in their own PR. Rename the billing pages to Subscription, Metered Billing, and Payment Methods and rewrite them. Rewrite Create an Instance and remove the sections flagged in review. Align the Markdown tables.
|
@JosiahParry Worked through all of it. This is now at a state which I am comfortable going with as the v1. Please have another check and merge if it seems good to you when no major rework is needed! |
3 participants
Add a Cloud documentation tab and rename the other tabs to Usage and Self-Hosted.
AI Summary
Why
The docs had two tabs, User and Admin, and no documentation of the managed cloud at all.
The only portal described anywhere was the license portal under Pricing, which is a different product.
What changed
A third top-level sidebar group, Cloud, in the
devversion.It is customer-facing only: the platform-admin console is deliberately out of scope.
cloud/quickstartcloud/organizations/1-organizationscloud/organizations/2-members-and-rolescloud/instances/1-create-an-instancecloud/instances/2-versions-and-upgradescloud/instances/3-custom-domainscloud.ricochet.rs, the OIDC callback, reverting to the default.cloud/instances/4-instance-accesscloud/instances/5-lifecyclecloud/instances/6-authenticationcloud/billing/1-subscriptioncloud/billing/2-metered-billingcloud/billing/3-payment-methodscloud/audit-logThe dev landing page gains a third
LinkCardpointing at the Cloud quickstart.The pages describe the actions that need explaining and the places where the portal and the ricochet app could be confused for each other, such as portal access versus in-app roles.
Self-explanatory UI actions are not documented.
Tab renames
Renamed in
dev.jsonandv0-18.json: User becomes Usage, and Admin becomes Self-Hosted.Versions 0.14 to 0.17 keep the old labels, as frozen snapshots.
Only the sidebar labels change, so
/user/...and/admin/...stay valid under every version and no external link breaks.Admin is renamed rather than kept because the word is now overloaded: it names an organization role in the Cloud tab and an instance role in the Self-Hosted tab.
Self-Hostedmatches the wording already used on the marketing site.Sidebar tab sizing
Self-Hostedwrapped because the tabs split the sidebar into equal columns, giving each 73px while the label needs 79px at the selected tab's 600 weight, so it broke at its hyphen.Each tab is now sized to its own label and the row is left-aligned, so all three fit side by side at Starlight's default 18.75rem sidebar and the short labels no longer carry wide empty margins.
Pages moved out of Self-Hosted
Two pages apply to any instance regardless of hosting, so they moved into Usage.
/dev/admin/technical/dependency-installation//dev/user/deployment/8-dependency-management//dev/admin/configuration/2-user-roles//dev/user/managing-content/0-user-roles/Dependency Management describes what happens on every deploy, so it is not a self-hosting topic at all.
User Roles describes what each role can do inside an instance, which is the same on either hosting.
Its
default_rolesnippet is the one self-hosted part, and it is replaced by a link to the configuration docs.The two inbound links to it, in
admin/configuration/0-overviewandadmin/configuration/1-authentication, are repointed.Both moves are
devonly, so no published URL changes and no redirects are needed.Everything else stays in Self-Hosted.
Audit logging, cookies, package repositories and deployment retention each document a
RICOCHET_HOMEpath or a config key that only a self-hoster can reach.Instance authentication
Organization owners and admins configure Authentication on an instance card to choose managed sign-in or an external OIDC provider.
Portal sign-in continues to use Ricochet Cloud accounts.
Native SAML, for both self-hosted instances and Cloud instances, is split out into a follow-up PR.
Sourcing
Written from
ricochet/saas-portalatcd23370, reading theapp/(cloud)/routes, their server actions,db/schema/enums.ts,db/entitlements.ts, andlib/billing/.Behaviour is described from the code rather than from that repository's
docs/, which is stale in at least one place:docs/instance-routing.mdstill documents an instance-id suffix in the hostname thathostnameForno longer emits.Validation
bun astro buildpasses andstarlightLinksValidatorreports all internal links valid.prek run -apasses every hook.scripts/semantic-breaks.mjsleaves the Cloud pages untouched, so the one-sentence-per-line rule holds.devrenders Usage, Self-Hosted, Cloud;v0-18renders Usage, Self-Hosted; andv0-17still renders User, Admin.