refactor(docs): rename SaaS → Account; integrate Guides under Account#7
Open
refactor(docs): rename SaaS → Account; integrate Guides under Account#7
Conversation
New: docs/Connector/permissions.md (sidebar_position: 2) — covers the four matrix capabilities (Sign in to client sites, View login activity, Create secrets, Manage secrets), Administrator-row immutability, REST endpoint behaviour, Approved-roles migration, submenu visibility, landing-page priority, integrator filters, and common scenarios. Three embedded screenshots captured by the new tests/e2e/permissions-doc spec at deviceScaleFactor: 3. The retired MANAGE_TEAMS cap is explicitly addressed via a callout explaining that team configuration is now restricted to WordPress administrators by design. Cap dependency section removed (the matrix no longer has any dependencies). Encrypted Messages rewrite: - Lede now opens with the customer-facing Grant Access form screenshot, showing where customers enter the message under the "Include a message for support?" panel. - Terminology unified on "message" / "message for support" (was "notification"). - Removed the Key Rotation Safety section (implementation detail). - Webhook is preserved everywhere — explicit "isn't going anywhere" note in the FAQ; older client SDKs continue using it for delivery, with the message simply not appearing inside the Connector plugin until the client updates to v1.10+.
Companion doc for the security-hardening change in the Connector plugin (commit bae87fd) that defaults envelope signature verification to hard-mode whenever a SaaS verification key is configured. Covers: - Why signature verification matters (compromised SaaS in scope per the threat model). - Two ways to wire the SaaS public key — option (set-and-forget via WP-CLI) and the saas-public-key filter (env-var-based for integrators who keep secrets out of the database). - What happens when no key is configured (legacy-compat mode + persistent admin notice). - Soft-mode escape hatch via the require-signature filter, scoped to short rollout windows. - Hooks reference for both filters with parameter table. The Connector's persistent admin notice now links here, so admins who see the warning have a one-stop guide for the fix.
The original draft told integrators to find the SaaS public key in "account settings" — that surface doesn't exist. Connector commit 6ca0456 ships TOFU + JIT auto-fetch as the default, so the actual happy path is "you don't have to do anything." Restructured around that reality: - "How it works (the happy path)" leads with auto-fetch + auto- rotation. Most integrators never touch a setting. - "When you'll see the admin notice" explains the only state where human action is needed (SaaS not signing or unreachable). - "Manually setting the key" demoted to an "advanced" section for integrators running self-hosted SaaS or wanting strict OOB trust. - "Disabling automatic key fetching" documents the `auto-fetch-key` filter as the strict-OOB escape hatch. - "Soft-mode rollout" kept for staging integrators. - Hooks reference adds the new `auto-fetch-key` filter.
"SaaS" was internal-architecture jargon — users don't think
"I'll go to the SaaS to update my plan." Renamed the docs section
to "Account", which is what customers actually call the
application at app.trustedlogin.com. Pairs naturally with Guides
and with Client SDK / Connector as a peer section.
Changes
-------
- `docs/SaaS/` → `docs/Account/` via `git mv` (preserves history).
- `sidebars.js`: `SaaS:` key + `dirName: 'SaaS'` → `Account` /
`dirName: 'Account'`. Sidebar header copy "The TrustedLogin
Application" → "Account" to match.
- `docusaurus.config.js`:
- Navbar item label "TrustedLogin SaaS" → "Account",
docId `SaaS/intro` → `Account/intro`.
- Footer link label "SaaS Application" → "Account",
path `/docs/SaaS/intro` → `/docs/Account/intro`.
- Redirects extended into two groups:
1. /SaaS/intro, /SaaS/data-storage, /SaaS/subcontractors —
identity map to the new /Account/* path. External links
and search-engine indexes preserve.
2. The previously-drafted internal-infra pages (vault*,
server-setup, CI-CD, cli, elasticsearch, webhooks,
user-remote-authentication) — same /SaaS/* → /Account/intro
collapse as before, plus parallel /Account/* → /Account/intro
entries for the new paths.
- `docs/Account/01-intro.md`: title `SaaS Intro` → `Account`,
H1 rewritten to drop the jargon.
- `docs/security.md`: `[SaaS Data Storage]` link → `[Account Data
Storage]` pointed at `/Account/data-storage`. The "Traefik
configuration" link to /SaaS/server-setup#traefik dropped (the
target page was draft-only and didn't render anyway).
- `docs/Account/server-setup.md` (still draft): "TrustedLogin SaaS
Server Setup" → "TrustedLogin Server Setup"; dead intra-doc link
to /SaaS/elasticsearch removed.
- `docs/Connector/encrypted-messages.md`,
`docs/Connector/troubleshooting.md`: customer-facing prose that
said "TrustedLogin SaaS" → "the TrustedLogin application" /
"app.trustedlogin.com" / just "TrustedLogin".
Out of scope (deliberately deferred)
------------------------------------
The infra-leftover files in the now-Account directory (CI-CD.md,
vault*.md, server-setup.md, elasticsearch.md, data-storage.md,
cli.md, subcontractors.md) describe internal Vault tokens / K8s /
Traefik / DigitalOcean infrastructure. They were marked draft+
redirected and shouldn't be in customer-facing docs at all. A
follow-up PR will move them out (probably back into the
trustedlogin-ecommerce internal docs/ folder where they belong)
and the redirect entries can drop entirely once that's done.
The doc-flow guides at docs/Guides/ were drafted but kept out of the published navigation. With the fixture rename (Team Andou / Team Beaufly / andou.test / beaufly.test) finalized in trustedlogin-ecommerce and screenshots regenerated, the guides are ready to ship — and they belong inside the Account section since they walk customers through Account-side tasks (signup, billing, 2FA, team switching, API keys).
Changes:
- Move docs/Guides/ → docs/Account/Guides/. Docusaurus autogenerated sidebar under Account picks up the subdirectory as a "Guides" category automatically.
- Refresh all 10 flow markdown files from the upstream source (trustedlogin-ecommerce/docs/flows/*.md) — the bodies match the renamed fixtures and the captured-from URL comments reflect today's regen.
- Refresh all flow screenshots in static/img/guides/{flow}/ from tests/Browser/docs/output/{flow}/ — the published PNGs now show "Team Andou / Team Beaufly" / "andou.test / beaufly.test" instead of "Playwright Team A/B" / "playwright-site-{a,b}.test".
- Rewrite cross-section relative links: ../{Section}/ → ../../{Section}/ (one level deeper now).
- Add docs/Account/Guides/_category_.json so the category sits at position 2 (right after the Account intro), expanded by default.
- Drop the obsolete `slug: /Guides` override from the Guides index — pages now publish at /Account/Guides/{flow}.
- Add /Guides/* → /Account/Guides/* client-redirects (belt-and-suspenders for any leaked link to the old top-level path).
- Update sidebars.js — remove the "Guides sidebar removed" placeholder; comment now records that Guides surface through Account's autogen.
- Update docusaurus.config.js navbar comment — Guides reach readers via the Account dropdown, not their own top-level item.
- Add a "Task guides" section to docs/Account/01-intro.md so the Account landing page links straight into the most-used flows.
Verified locally with `npx docusaurus build` — clean build, no broken-markdown warnings.
zackkatz
changed the title
…ignup reorder Round 1 of the post-preview cleanup (per @zack): - Delete 9 internal infrastructure pages from docs/Account/ that were never meant to ship as public docs (server-setup, cli, elasticsearch, vault, vault-client, vault-sass-token, user-remote-authentication, webhooks, CI-CD). The redirects already mapped /Account/<page> → /Account/intro; the files were keeping the redirect from firing because Docusaurus served the page directly. - Drop the "Server Setup" section from docs/Account/01-intro.md — its only link pointed at the deleted server-setup page, and the prose was infra/jargon that didn't belong on a customer-facing landing page. - Strip the dev-internal note from docs/Account/Guides/install-connector.md ("...regenerates against a docker-bootstrapped Connector install. If your local :8100 is a different WordPress install, set PLAYWRIGHT_CONNECTOR_URL...") — that's spec-author guidance, not customer-facing copy. The matching outro was also dropped from the upstream spec in trustedlogin-ecommerce so it stays out on next mirror. - Sync docs/Account/Guides/signup.md to the latest upstream regen — 2FA enrollment is now step 4 (post email-verification, pre-dashboard) per the actual CheckGoogle2FA enforcement, not step 6 as it incorrectly read before. Screenshots renamed accordingly. Known follow-ups (not in this commit): - install-connector steps 1/2/3 capture identical screenshots — the spec stays on the same /admin/team-settings DOM state with no scroll/focus/fill between captures. Needs flow.focus() targeting on the "Team identity" form section + "API credentials" section in a separate spec rewrite. - log-in-to-site has a "Revoking access" prose section in the outro but no accompanying screenshot. Needs a flow.step() for the site-detail Danger zone in a separate spec change.
…sidebar rename)
User feedback on the localhost preview:
- switch-team: ⌘K and Ctrl+K now wrap in <kbd> for proper keyboard-key rendering instead of bold text. Mirrored from upstream spec change.
- change-plan: drop "— upgrades are atomic" from the step-4 heading; the body still explains prorate / no-double-billing semantics in plain language. Mirrored from upstream.
- reset-2fa: replace [email protected] obfuscation placeholder (Cloudflare email-protection isn't running on docs.trustedlogin.com) with literal support@trustedlogin.com. Mirrored from upstream.
- signup: rewrite cross-section relative links to ../../ — they were broken because the upstream lives at docs/flows/signup.md (one level deep) and the mirror lives at docs/Account/Guides/signup.md (two levels deep). The mirror script needs cross-section awareness; deferred as a separate concern.
- regenerate-api-keys: rename sidebar_label "Regenerate API keys" → "Manage API keys". The guide actually covers finding keys, sharing them with a developer, emergency pause, and when to ask for rotation — broader than just "rotate". Sidebar now matches the H1 ("Manage your API keys") and the body's actual scope.
- Client/01-intro: drop the broken bugsnag.com link (article 404s); keep the heading text "Be secure and don't crash sites" since the principle still stands.
Refreshed PNGs for the three regenerated specs (switch-team, change-plan, reset-2fa). Old change-plan files 03/04 PNGs got renamed by the spec — the mirror cleanup picks up the new "or-switch-plans-in-the-picker" name.
Known follow-ups (not in this commit):
- invite-teammate screenshots show empty states (no pending invites, no extra teammates seeded). Needs fixture seeder updates.
- install-connector steps 1/2/3 still capture the same DOM state. Needs flow.focus() targeting per-section.
- log-in-to-site missing a "Revoking access" screenshot for the Danger zone affordance.
- HTTP API section in /Account/intro: external links to app.trustedlogin.com/docs/api/ — pending decision on whether those external docs are publicly accessible / appropriate for customers.
…n screenshots
Address feedback from the second preview pass:
- HTTP API: removed from /Account/intro (it's developer-facing, not customer-facing). New top-level page at /api-reference linked from the Home sidebar (alongside Getting Started, Security, Flows, For AI tools). The Account intro now just nods at it once for builders who need it.
- Invite teammate (mirror sync): the spec now sees a real pending invitation on Team Andou (seeded upstream as `pending-teammate@andou.test`), so step 2 ("Review pending invitations") shows actual data instead of an empty-state placeholder. Steps 1 and 5 (teammates list) already had data — the seeder attaches member-a + admin-a to Team Andou.
- Install Connector: steps 1, 2, and 3 used to capture the same /admin/team-settings full-page DOM, producing identical screenshots. Upstream spec change rewrites steps 2 and 3 to flow.focus() onto the labeled `identity-heading` and `api-heading` sections; mirror picks up three visually distinct images.
- Log in to a customer site: added a new step 6 capturing the Danger zone with the Revoke access button. The redundant "## Revoking access" prose section is dropped from the outro since step 6 covers it. Mirror also picks up the cross-section path fix (`../Connector/...` → `../../Connector/...`).
The upstream spec + seeder changes are pushed to PR #901; this PR mirrors the regenerated outputs.
…s" crop
Two changes in this push.
1. New top-level Developers section
Customer-facing and engineer-facing docs were interleaved in the previous
structure: /Client (entirely SDK / dev), /Connector (mostly user-installable
plugin docs but a chunk of internals), and /Account (customer experience +
one HTTP API stub). This split readers across three sections to find their
audience.
New layout:
/Account — customer landing + Guides/ flows
/Connector — install + permissions + troubleshooting + help-scout
/Developers — Client SDK, Connector internals, HTTP API
/Developers/Client/* — wholesale move from /Client/*
/Developers/Connector-{development, hooks, encrypted-messages,
envelope-signature-verification, secrets,
running-behind-a-proxy} — was /Connector/*
/Developers/http-api — was top-level /api-reference
/Developers/intro — new landing page that orients readers
sidebars.js: remove the standalone Client section, drop api-reference
from Home, add a new Developers section. Connector and Account are
unchanged in shape, just lighter in content.
Navbar + footer: replace the "Client SDK" item with "Developers"; the
Connector and Account items keep their existing positions.
Redirects: Group 4 in the client-redirects plugin maps every old path
(page-by-page for Client, by-name for the moved Connector files, plus
/api-reference) to its new home, so external bookmarks and search-
engine links keep working. /Client/* and /api-reference will arrive
at the right doc; /Connector/* paths that didn't move are unaffected.
Cross-section links inside the moved docs and across the rest of the
site are rewritten to the new locations. `npx docusaurus build` runs
clean — zero unresolved markdown links.
2. /Account/Guides/change-plan step 5 image — better aspect ratio
The "Your credits stay yours" capture was a thin extreme-aspect band
because the focus locator hugged a full-width <p>. Switched to the
inner <strong> element with padding=64; the screenshot is now a
readable rectangle instead of a sliver. Mirror picks up the new PNG.
(Old change-plan step-4 PNG `04-or-pick-a-new-plan-in-the-picker-upgrades-are-atomic.png`
left from the pre-rename run is also cleaned up here.)
…er Connector + Account Per @zack: a top-level /Developers/ section pulled too much content out of its natural home. Customers looking for the WordPress plugin shouldn't have to chase Connector internals across two top-level sections, and Account-side reference material for builders belongs adjacent to the Account experience. New shape: /Client/* — wholesale restored to top-level (the SDK is a single dev product; it stays its own section) /Connector/* — user-installable plugin docs at top /Connector/secrets — moved back here from /Developers/Connector-secrets, since secret management is something Connector operators do, not just plugin developers /Connector/Developers/ — new subcategory for engineer-audience Connector material development.md hooks.md encrypted-messages.md envelope-signature-verification.md running-behind-a-proxy.md /Account/* — customer landing + Guides /Account/Developers/ — new subcategory for engineer-audience Account material http-api.md — was /api-reference, briefly /Developers/http-api Sidebar: restore the standalone Client section, drop the Developers section (the autogen sidebars under Connector and Account pick up the new sub-Developers categories automatically via _category_.json with position 9 to keep them at the bottom of their parent). Navbar + footer: restore the "Client SDK" item; the Developers item is removed. Connector and Account positions unchanged. Redirects: swap Group 4 to point in the new direction. Any /Developers/* URL grabbed during the brief window the section existed redirects to its real home: /Developers/Client/* → /Client/*, /Developers/Connector-{dev,hooks,encrypted-messages,envelope-signature-verification,running-behind-a-proxy} → /Connector/Developers/*, /Developers/Connector-secrets → /Connector/secrets, /Developers/http-api → /Account/Developers/http-api. The legacy /api-reference (top-level) redirect is also re-targeted to /Account/Developers/http-api. Cross-section links inside the moved docs and across the rest of the site are rewritten to the new locations. `npx docusaurus build` runs clean — zero unresolved markdown links. Note on /Account/Guides/Client/login-feedback-flow screenshots: the user reported tight cropping is needed. Those PNGs (10–15 of them in /img/client/login-feedback/) are full-viewport 1280×720 captures — there's no Playwright spec generating them, so an in-tree fix would require building a new spec that drives the Client-SDK grant flow on a vendor site and uses flow.focus() per banner. Deferred as a separate task.
Encrypted Messages is documented as if it's live ("Connector v1.4+,
enabled automatically"), but neither side actually implements it:
- trustedlogin-ecommerce has no /messages buffer endpoint, no migrations
for an envelopes table, and no `customer_message` field anywhere.
- trustedlogin-connector v1.5.0 has no scheduled poller, no
`trustedlogin_connector/message_received` action, and no
Endpoints/Messages handler. The Encryption.php class that exists is
for the access-key envelope (the original auth flow), not for buffered
customer messages.
Pull the page so the public docs don't promise a feature customers
can't use. Add redirects from /Connector/encrypted-messages and the
brief /Developers/Connector-encrypted-messages window to /Connector/
intro, and drop the unused 01-grant-access-message screenshot.
Reintroduce the page when the feature ships.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
"SaaS" was internal-architecture jargon — users don't think "I'll go to the SaaS to update my plan." Renamed the docs section to Account, which is what customers actually call the application at app.trustedlogin.com. Pairs naturally with Guides and with Client SDK / Connector as a peer section.
What changed
docs/SaaS/→docs/Account/viagit mv(history preserved per file).sidebars.js:SaaSkey +dirName: 'SaaS'→Account/dirName: 'Account'. Sidebar header copy "The TrustedLogin Application" → "Account".docusaurus.config.js:TrustedLogin SaaS→Account(docId follows).SaaS Application→Account./SaaS/intro,/SaaS/data-storage,/SaaS/subcontractors— identity-map to the new/Account/*path./SaaS/* → /Account/introcollapse as before, plus parallel/Account/* → /Account/introentries for the new paths.docs/Account/01-intro.md:SaaS Introtitle + jargon-y H1 rewritten.docs/security.md: link to/SaaS/data-storagere-pointed; broken/SaaS/server-setup#traefiklink dropped (target was draft-only and 404'd anyway).docs/Account/server-setup.md(still draft): H1 + dead/SaaS/elasticsearchlink cleaned up.docs/Connector/encrypted-messages.md,docs/Connector/troubleshooting.md: customer-facing prose using the term "TrustedLogin SaaS" → "the TrustedLogin application" / "app.trustedlogin.com".Out of scope (next PR)
The infra-leftover files now under
docs/Account/(CI-CD.md, vault*.md, server-setup.md, elasticsearch.md, data-storage.md, cli.md, subcontractors.md) describe internal Vault tokens / K8s / Traefik / DigitalOcean infrastructure. They were already marked draft + redirected, but they shouldn't be in customer-facing docs at all. A follow-up PR will move them out (probably back intotrustedlogin-ecommerce/docs/) and the redirect entries can drop entirely once that's done.Test plan
mirror-md.jsregenerates without errors against the new path).https://docs.trustedlogin.com/SaaS/intro302/JS-redirects to/Account/intro(and the other 11/SaaS/*redirects work)./Account/intro.