Skip to content
froggDocs

Writing docs

The documentation you are reading is in the repository and ships with the code. A pull request that changes what users see or configure updates the matching page in the same pull request.

Where things live

Section titled “Where things live”
Path Contents
website/src/content/docs/docs/<section>/*.mdx Pages, served at /docs/<section>/<page>/
website/src/assets/docs/** Screenshots and images
website/src/components/docs/ Docs components (Screenshot, Terminal, BrandPreview)
website/COMPONENTS.md Component API
scripts/docs/capture-screenshots.mjs Regenerates screenshots from a running daemon
skills/frogg-docs/SKILL.md Page map and checklist for agents updating docs

Sections are directories; the sidebar is generated from each page’s sidebar.order.

When to update docs

Section titled “When to update docs”

Update docs in the same pull request when you change:

  • user-visible behaviour or UI (update screenshots too),
  • config.json keys, environment variables, frogg.json or brand.json,
  • CLI commands or flags,
  • protocol-visible features or capabilities clients depend on,
  • install, update, branding, build or release pipelines.

Tick Docs updated (or not needed) in the pull request template.

Style

Section titled “Style”
  • Task first: say what the reader wants to do, then the command.
  • Short sentences. Expert audience; skip marketing and filler.
  • Real commands, real config, real output. Run them.
  • frogg is pronounced F.D.E.: write a frogg, never “a frogg”.
  • Document what the code does today. If a feature is partial, experimental, preview or unvalidated on a platform, say so plainly. Never document planned features as present.
  • Link with root-relative paths and a trailing slash: /docs/self-hosting/updates/.

Components

Section titled “Components”
import { Screenshot, Terminal, Steps, Aside, Tabs, TabItem } from "@/components/docs";
import timeline from "@/assets/docs/app/agent-timeline.png";


<Screenshot src={timeline} alt="Completed agent timeline" />
<Terminal code="curl -fsSL https://frogg.app/install.sh | bash" />

See website/COMPONENTS.md for every prop.

Screenshots

Section titled “Screenshots”

Screenshots are captured from a real daemon’s web app with headless Chromium, in dark theme. Never mock UI.

Terminal window
npm ci
npm run build:server && npm run build:daemon-web-ui
FROGG_HOME=/tmp/frogg-docs-home node apps/cli/bin/frogg start --listen 0.0.0.0:17900 --web-ui --no-relay
node scripts/docs/capture-screenshots.mjs --url http://127.0.0.1:17900 --seed
node scripts/docs/capture-screenshots.mjs --list
node scripts/docs/capture-screenshots.mjs --url http://127.0.0.1:17900 --only app/home,app/host-providers

--seed adds a demo project. Shots that need an agent timeline or a pending permission need an agent run in that project, which uses provider credits; run one yourself before capturing those. Keep each image under 300 KB; the script optimises PNGs.

For branded screenshots, build with FROGG_BRAND_DIR=brands/example in a separate worktree and pass --brand-tag acme.

Preview and check

Section titled “Preview and check”
Terminal window
cd website
npm ci
npm run dev        # http://<host>:4321/docs/
npm run build && npm run linkcheck