Writing docs with Windsurf

Windsurf is Codeium's editor — a VS Code fork with "Cascade", an agent that plans multi-step edits across files. Unlike Cursor's inline-first approach or Claude Code's terminal-first approach, Windsurf sits between them: GUI-first, but agent-capable. Good match for docs teams with non-developer writers who'd struggle in a terminal but want agent-level help.

This page gives you Windsurf-specific rules + prompt patterns for NookDocs repos.

Install + setup

The .windsurf/rules/nookdocs.md template

Windsurf's rules files are plain Markdown — Cascade treats them as persistent context that applies to every agent action in the repo.

# NookDocs authoring rules

This repo is a NookDocs documentation site. Pages live under `docs/`,
config at `nookdocs.config.json`.

## Component library

Full spec: https://nookdocs.com/nookdocs-components.llm.md

Use these components (don't invent others, don't import anything):

**Content**
- `<Callout type>`, `<Note>`, `<Tip>`, `<Warning>`, `<Info>`,
  `<Danger>`, `<Check>` — inline notices
- `<Badge>`, `<Pill>`, `<Tag>`, `<Kbd>` — inline labels
- `<Snippet>` — reusable content (inline children until Phase 4
  file-based ships)

**Layout**
- `<Card title icon href>`, `<CardGroup cols>` — card grids
- `<Tile>`, `<Tiles cols>` — lighter alternative to cards
- `<HeroCard>`, `<LinkCard>` — landing-page + link affordances

**Code**
- `<CodeGroup>` — tabbed multi-language code blocks
- `<CodeBlock>`, `<TerminalBlock>` — single-language
- `<RequestExample>`, `<ResponseExample>` — API-specific wrappers

**Navigation**
- `<Tabs>` + `<TabsList>` + `<TabsTrigger>` + `<TabsContent>`
- `<Accordion>` + `<AccordionGroup>` + `<AccordionItem>` +
  `<AccordionTrigger>` + `<AccordionContent>`

**Procedural**
- `<Steps>` + `<Step title="...">` — ordered instructions

**Media**
- `<Frame caption>` — wrap images with caption
- `<Image>`, `<Video>`, `<Embed>`, `<Mermaid>`

**API**
- `<ParamField path type required default>` — request params + config
  keys
- `<ResponseField name type>` — response body fields
- `<ApiMethod>` — endpoint header

**Meta**
- `<Update date label version tags>` — changelog entries
- `<Visibility for="humans|agents">` — audience-split content
- `<Tooltip>`, `<View>`, `<Expandable>`, `<Prompt>`

## Frontmatter

Every page:

    ---
    title: Page title (verb-first for how-tos)
    description: 1-sentence specific pitch, 140-160 chars.
    icon: lucide-icon-name
    ---

Changelog pages add `rss: true` to expose the RSS subscribe button.

## Authoring discipline

1. Second person, active voice, imperative for instructions.
2. Lead with the answer. Skip "In this guide we will..." intros.
3. Verb-first H2 headings for how-to sections.
4. `<ParamField>` for every config key + API param.
5. Fenced code blocks with language tags — always.
6. Multi-language examples go in `<CodeGroup>`.
7. Cross-link to 3-5 related pages in `## Related` at the bottom.
8. `<Visibility for="agents">` for LLM-directive content;
   `<Visibility for="humans">` for UI-only content.

## Verification (run after every edit)

```bash
# Parse-check
node --input-type=module -e "
  import { mdxParse } from 'safe-mdx/parse';
  import { readFileSync } from 'fs';
  mdxParse(readFileSync('docs/PATH.mdx','utf-8'));
"

# Cross-layer sync (config changes)
npm run check:sync

Things NOT to do

• No ES imports in MDX. Components are globally available.

• No HTML tags (use the components listed above).

• No marketing language in reference docs ("powerful", "seamless", "easily", "simply" — all banned).

• No <h1> in the body — the title comes from frontmatter.

• No orphan pages. Every new page links from at least one sibling.

Commit this at `.windsurf/rules/nookdocs.md`. Cascade uses it as persistent context.

## Cascade workflows

Cascade is Windsurf's multi-step agent. Three patterns that work well for docs:

### Cascade pattern 1: "Add a new page with full nav integration"

Open Cascade (Cmd/Ctrl+L), write:

```text
Create a new documentation page at docs/configuration/webhooks.mdx covering
webhook configuration. Use the structure from docs/configuration/feedback.mdx
as a template. The page should cover:

- Retry policy (ParamField for maxRetries, backoffStrategy, retryDelay)
- Signature verification (ParamField for secret, algorithm)
- Payload schema (ResponseField for each field in the webhook body)

Include one complete JSON example at the end showing all fields set.

Then add the page to nookdocs.config.json navigation under the Configuration
group, positioned after custom-domain.

Finally run parse-check + npm run check:sync to verify no errors.

Cascade plans the steps (create file → write content → update nav → run checks), executes them in order, shows you the diff per step. Approve or redirect at each step.

Cascade pattern 2: "Audit + fix across multiple pages"

Audit every file in docs/integrations/analytics/ against these rules:
1. Frontmatter has title + description + icon
2. Description is 100-160 chars and specific (not generic)
3. ParamField present for integrations.<key> with required + type
4. Related section at the end with 3-5 cross-links

List issues per file, then fix all of them in a single batch commit.

Cascade loops through each file, reports, then fixes. Useful for enforcing consistency across similar pages (integrations, API endpoints, component references).

Cascade pattern 3: "Follow the link to fix a downstream ref"

I renamed `docs/features/copy-for-llms.mdx` to
`docs/optimize/markdown-export.mdx`. Find all internal links pointing at
the old path across docs/ and fix them. Also add a redirect entry to
nookdocs.config.json#redirects so external inbound links don't 404.

Cascade handles the multi-file edit + the config update. Verify with a grep before accepting.

Cascade vs Chat vs Command

Windsurf has three editor-level interaction surfaces:

Typical docs workflow uses all four: Autocomplete for typing speed, Command for targeted rewrites, Cascade for new pages + refactors, Chat for "how does X work" questions.

Non-developer writer workflow

Windsurf's GUI-first nature makes it the easier onboarding for writers without terminal experience. Baseline workflow:

Writers without Git background can be productive in Windsurf within ~30 minutes of pairing with an engineer for the first task.

What Windsurf does well

• GUI-first editing for non-dev writers. Source Control panel replaces terminal for the common git tasks.

• Cascade multi-step planning. Transparent plan-and-execute; writer can intervene between steps.

• Persistent rules files — .windsurf/rules/ applies repo-wide context to every Cascade session.

• Global memory — Windsurf can remember personal authoring preferences across repos.

• Fast tab-complete — Codeium's underlying model is optimised for latency.

What Windsurf doesn't do well

• Single-line tight edits. Cascade has overhead; for a two-word typo fix, direct edit is faster.

• Terminal-heavy workflows. Engineers working on build pipelines + CI often prefer Claude Code.

• Custom / less-common models. Windsurf's model menu is narrower than Cursor or Claude Code. Primarily Codeium + Anthropic + OpenAI options.

Collaboration pattern

If your team splits writers + engineers across Windsurf + Cursor / Claude Code, keep the context files in sync:

.windsurf/rules/nookdocs.md   ← Windsurf writers read this
.cursor/rules/nookdocs.mdc    ← Cursor engineers read this
AGENTS.md                       ← Claude Code reads this

All three files can have similar content with format differences. Keep the source of truth in AGENTS.md; mirror to the other two. Nothing prevents you from committing all three — each tool reads its own.

Related

• Claude Code — CLI agent sibling

• Cursor — editor-based sibling (more inline-first than Windsurf)

• Writing for LLMs — broader theory

• Component spec — the URL all three tools reference

• Style and tone — the authoring rubric the rules enforce