Skip to content

docs(quickstart): owner role wording, skipped passkey, troubleshooting, verify, and footer products #175

Open

Description

@Bccorb

Following https://docs.seamlessauth.com/start/quickstart/ against v0.23.0 (seamless-cli 0.30.0) worked through email-code sign-in and the admin console, with these gaps in the page itself.

1. "Grants the admin role" is not what happens

Step 6 says the auth server "grants the admin role to the account created with that address". The account gets admin:write, and the starter shows user, betaUser, admin:write. The generated AVAILABLE_ROLES also contains a separate admin role, so a reader looking for admin on their account thinks the grant failed. start/firstAdmin.mdx already says admin:write correctly.

Repro: run the quickstart as written, register with the init email, read the roles on the starter's home page.

2. Skipping the passkey is not covered

Step 6 says "enroll a passkey when prompted", but the starter offers "Skip for now". A user who skips is signed in as the owner and can open the console, but every write (for example creating a permission on the Roles page) is refused with "A security key or authenticator is required". The console message is clear. The quickstart should say before step 6 that admin changes need a passkey or authenticator app, so skipping now means enrolling later from the profile.

Repro: in step 6 click "Skip for now", open http://localhost:3000/console/roles, click New permission, create reports:read.

3. No troubleshooting for the two failures a returning or busy developer hits

  • Port 5173 already taken by another Vite server: localhost:5173 opens the other app, and nothing reports it (filed as a CLI issue).
  • Re-running with a name used before (the page's own my-app): docker compose up reuses old images and the API crashes with does not provide an export named 'requirePermission' (filed as a CLI issue). Telling readers to run docker compose up --build avoids it.

A short Troubleshooting section after step 5 covering both would save the first-run failures.

4. verify is listed as a user command

"This will show: Every command (init, templates, check, verify, ...)" and "A CLI that can also check the generated stack" lead readers to seamless verify, which needs a seamless-auth-api checkout and fails from a scaffolded project. Name seamless check as the command for checking the generated stack, and leave verify to contributor docs.

5. Footer names discontinued and frozen products

The site footer, on every page including the quickstart, lists "Part of the Fells Code family: Seamless Auth, Seamless Secrets, Review Board, Seamless CLI, Seamless Glance". Review is discontinued and Glance is frozen.

Found running the self-hosted quickstart against v0.23.0 (seamless-cli 0.30.0) for fells-code/seamless-auth-api#561.

Activity

  1. added this to the v0.24 milestone on Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions