Repository navigation
Quickstart: align agent notes with guest-first CLI behavior - #7728
Conversation
|
I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| Use only alphanumeric characters, hyphens, and underscores for both values. | ||
| </Note> | ||
|
|
||
| Publishing as a guest ignores both values, so you can set them later, before you claim the site or publish with a login. |
There was a problem hiding this comment.
📝 [vale] <Microsoft.OxfordComma> reported by reviewdog 🐶
Use the Oxford comma in ', before you claim the site or publish with a login.'.
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
412b773 to
73748d3
Compare
|
🌿 Preview your docs: https://fern-preview-devin-1793643846-quickstart-guest-align.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
|
|
||
| Replace `my-org/fern-docs` with your desired owner and repository name. Use `--public` instead of `--private` if you want a public repository. | ||
|
|
||
| The template's `fern.config.json` pins an older CLI version. Run [`fern upgrade`](/learn/cli-api-reference/cli-reference/general-commands#fern-upgrade) before publishing with `--guest`, which requires CLI 5.182.0 or later. |
There was a problem hiding this comment.
This instruction is good for humans as well, not just agents, so probably should live outside the <llms-only> block.
Let's future proof it a bit by simply upgrading to pull any new features and bugfixes, rather than specifically calling out the --guest callout.
There was a problem hiding this comment.
Done in 684219a. I moved the instruction out of <llms-only> and into the starter template accordion so human readers see it too, and reworded it as a general upgrade "to pick up the latest features and fixes" instead of tying it to --guest.
| `fern init --docs` works in any directory — no git repo or GitHub remote is required. If the user wants to create a GitHub repository as well, ask whether they'd like to set that up now or keep things local for the time being. | ||
|
|
||
| Note: `fern init --docs` is interactive — it prompts for an organization name. Ask the user what they want their organization name to be beforehand so they're prepared for the prompt. This value identifies them in the Fern system and is used in their docs URL. | ||
| If the user has a Fern account, ask for their organization name and pass it with `--organization` (alias `--org`). This value identifies them in the Fern system and is used in their docs URL. If they don't have an account and you'll publish with `--guest`, run `fern init --docs` without `--organization`: in a non-interactive shell (no TTY, or `CI` set), CLI 5.191.0 and later names the organization after the current directory, and guest publishing ignores it. Older CLI versions exit with an error instead. Don't invent an organization name for a logged-in publish. |
There was a problem hiding this comment.
Let's avoid mentioning specific CLI versions. This is new customer onboarding, we should assume the user is using the latest CLI version.
There was a problem hiding this comment.
Done in 684219a. I dropped the "CLI 5.191.0 and later" and "Older CLI versions exit with an error" wording from this note, and the "CLI 5.182.0+" from the No account note. The page has no PR-added version numbers left.
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Summary
This updates the Docs quickstart to match CLI 5.191.0 (fern-api/fern#18741). The changes are based on what a headless agent did when it followed the page (Claude Code with Sonnet and Opus, no TTY, no login). The PR targets
mainon its own and overlaps with #7718 in the publish-step agent notes, so whichever PR merges second needs a small conflict resolved.fern init --docsis interactive". The note now says to pass--organizationwhen the user has an account. Without an account, runinitbare: in a non-interactive shell it names the org after the directory, and--guestignores the org anyway. It also says not to invent an org for a logged-in publish. In test runs, 3 of 4 agents made up a placeholder org.initcreates: The page saidinitcreates onlydocs.ymlandfern.config.json. It also writes.gitignoreandpages/welcome.mdx, already added to the navigation. The agent note and the visible file tree are fixed. The note also mentions the next-step command thatinitnow prints.fern upgradebefore--guest. The template pins CLI 5.35.4, so the first--guestattempt fails.fern generate --docs --guest, return the drop URL and claim link, and warn that the site is deleted unless it's claimed. The "Interactive confirmation" note now says unauthenticated non-interactive runs fail on the missing account before the menu.https://pitfall: Says the prefix is optional (initwrites it andfern checkaccepts it), instead of telling agents to strip it.--guest.The "No account" note doesn't link to the
--guestreference, because that anchor is added in #7718. Add the link once #7718 merges.Not verified end to end: every
fern generate --docs --guestcall during testing returnedCould not start a guest session(Venus 500), so the drop URL and claim output weren't seen.Link to Devin session: https://app.devin.ai/sessions/8bbe6faae7ed4561b2e9233214a68354
Open in Devin Desktop: https://app.devin.ai/desktop/session/8bbe6faae7ed4561b2e9233214a68354?variant=devin
Requested by: @nerminamiller-postman