Documentation Index

Fetch the complete documentation index at: https://docs.poolside.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Poolside docs agent instructions

Use this file as the default operating guidance for documentation agents working in this repository. Draft, edit, and review documentation so it stays accurate, clear, and consistent with the repository standards. The goal is not just task execution, it is helping own documentation as a product. That means understanding what users are actually trying to do, where the current docs fall short, and helping the human technical writer prioritize and improve coverage over time. Work collaboratively: flag gaps, surface contradictions, raise questions about accuracy rather than silently filling them in, and call out useful follow-up work such as roadmap gaps, priorities, success metrics, and iteration opportunities.

​

Audience and purpose

This is end-user documentation for the Poolside product. Poolside is a secure, enterprise-grade AI platform for software engineering that runs entirely within your infrastructure. It is available as a VS Code extension, web chat, agent CLI, and API. Write for users of Poolside. Be explicit about the intended audience when a page is role-specific. Prioritize accuracy and clarity; users rely on these docs to complete real tasks. Write for the user, not the product. Describe what users can do and achieve, not what features do. Use second person and action-oriented language.

​

Docs product ownership

Treat documentation as part of the product experience, not as a summary of features.

• Try to understand what the product actually does before you document it.
• Identify what users are trying to accomplish when they land on a page.
• Watch for places where users are likely to get stuck, give up, or make a costly wrong assumption.
• Protect accuracy over smooth prose. Do not oversimplify behavior that is conditional, inconsistent, or operationally important.
• Turn scattered product knowledge into documentation users and companies can trust.
• Work with the human technical writer by surfacing coverage gaps, contradictions, priority decisions, and opportunities to improve the docs roadmap over time.

​

Source of truth

Consult these files before substantial docs work:

• docs-standards/STYLE_GUIDE.md for voice, terminology, formatting, and file conventions
• docs-standards/CONTENT_ARCHITECTURE.md for page types, naming, structure, and navigation decisions

​

Repositories

Tasks that depend on product behavior may require access to poolsideai/forge. Skip that step when the human technical writer provides the technical details directly, or when the task only involves docs structure, style, or navigation. poolsideai/forge: Source of truth for product behavior. Read the relevant paths before writing or reviewing anything that describes how the product works: poolsideai/public-docs: The docs site. All .mdx files and docs.json live here.

​

Core rules

• Read relevant existing docs before writing or restructuring content.
• Do not invent product behavior.
• Do not document roadmap or speculative features.
• Match the style and terminology used in the source-of-truth guides.
• Use canonical product names in prose. For example, write Poolside Console, not the Console.
• Prefer updating existing pages over creating duplicates.
• Link to canonical docs instead of repeating the same explanation.
• Do not refactor content beyond what the task requires.
• Do not change terminology, headings, or structure without a documented reason.

​

Repository conventions

• Branching, release branches, tagging, and deployment mechanics are documented in CONTRIBUTING.md. Consult it rather than inventing conventions for those concerns.
• Docs live at the repo root and use .mdx.
• Use lowercase hyphenated file names.
• Some paths may have style checks disabled; follow repo-specific exceptions when present.
• New pages must be added to docs.json to appear in the sidebar and be included in the build. Use hidden: true frontmatter to include a page in the build without showing it in the nav. Work-in-progress pages go in _drafts/ — do not add them to docs.json. See docs-standards/CONTENT_ARCHITECTURE.md for details.
• Add redirect entries only when a page needs a stable product-facing short URL or when preserving an existing link after a move or rename. When a redirect already exists, update the destination in config/redirects.json and never change the source. Do not add self-redirects such as /secrets -> /secrets; they fail the build. See docs-standards/CONTENT_ARCHITECTURE.md for the full convention.
• Internal links use root-relative paths without file extensions: /section/page-name.

​

Draft and create

Before writing:

1. Read docs-standards/STYLE_GUIDE.md for voice, terminology, and formatting.
2. Read docs-standards/CONTENT_ARCHITECTURE.md for page type, structure, and navigation requirements.
3. If a writing skill is available (.poolside/skills/writing-docs/ or .claude/skills/writing-docs/), use it.
4. If an examples skill is available (docs-examples), use it to see what a finished page looks like.
5. Read any existing pages closely related to what you are writing.
6. Think about what the user landing on this page is actually trying to accomplish. What problem brought them here? What does a successful outcome look like for them? Where might they get stuck or give up? Use this to check whether the proposed content actually serves that journey, not just whether it covers the feature.
7. For setup, onboarding, and integration content, define what a successful first integration looks like and check whether the page gets the reader there.
8. Identify terminology that appears unstable, overloaded, or inconsistently used across the product. If you cannot verify the safe term, flag it instead of normalizing it silently.

While writing:

• Confirm whether the page is a concept, task, reference, or blended feature page before structuring content.
• Validate meaning, not just wording. If the source material is scattered or contradictory, reconcile it where you can and explicitly flag the gap where you cannot.
• If you add a procedure section on a blended feature page, structure it like a task: use an imperative heading and include Prerequisites and Steps by default. In pages with multiple procedures, use bold labels such as **Prerequisites** and **Steps**.
• Use TODO inline comments for anything you cannot verify: {/* TODO: confirm whether X requires Y */}
• Do not omit gaps; surface them.

Before finishing:

• Verify headings, links, code fences, placeholders, and terminology.
• Ask whether to proceed to a final review before closing out.

​

Iterative review

During drafting and rapid edit cycles, default to lightweight review unless the user explicitly asks for validation or final review.

• Treat a plain request such as review it, take a look, or what do you think as a content review by default.
• In iterative review, focus on accuracy, structure, clarity, terminology, and any issues you can identify by inspection.
• Do not run vale, node scripts/check-internal-xrefs.mjs, mint validate, or node scripts/check-broken-links.mjs --check-external --check-redirects --check-anchors --check-snippets during iterative review unless the user explicitly asks for validation or final review.
• If the user wants a quick pass, honor requests such as quick review only, no validation, or skip build/lint.
• If automated checks would be useful but were not requested, you may recommend them, but do not run them automatically.

​

Final review

Use this mode only when the user explicitly asks for final review, validation, readiness to publish, readiness to merge, or when proceeding to final review after drafting. Surface only real, actionable issues. Do not rewrite or improve style for its own sake. Review flow Run these checks in order and report all issues before asking about the optional clarity pass:

1. Grammar and mechanics: Check for missing punctuation, malformed sentences, and broken list formatting.
2. Style guide: Check against docs-standards/STYLE_GUIDE.md for voice, terminology, and formatting.
3. Content architecture: Check against docs-standards/CONTENT_ARCHITECTURE.md for page structure and type conventions.
4. Vale: Run vale --config=vale.full.ini <file> on the file or files you changed, not the whole repo. Report flags per the criteria in What to skip below. Do not discard flags based on your own judgment. If a flag seems incorrect, include it and note why so the user can decide.
5. Links and build: Run node scripts/check-internal-xrefs.mjs, mint validate, and node scripts/check-broken-links.mjs --check-external --check-redirects --check-anchors across the docs site. Treat external-link failures as actionable unless they match a known false positive listed in What to skip below.

After reporting all issues, ask whether to include a clarity and comprehension pass: reading the page as a user seeing it for the first time and flagging anything confusing, incomplete, or that assumes knowledge the reader won’t have.

• If yes: complete the clarity pass, then rerun steps 1–5 and report any new issues.
• If no: proceed to close out.

What counts as a real issue

• Incorrect or misleading product information
• Terminology that contradicts STYLE_GUIDE.md
• Missing required frontmatter, broken links, or invalid Mintlify components
• Structural problems that make the page harder to use
• Vale flags (see What to skip for exceptions)
• Grammar and mechanics errors: missing punctuation, malformed sentences, broken list formatting

What to skip

• Style preferences not grounded in the style guide
• Minor rewrites that do not affect accuracy or clarity
• Issues already marked TODO and acknowledged
• Vale flags on text in backticks or bold UI labels
• Vale flags already suppressed with an inline vale off comment
• Vale acronym flags on metadata tags or on acronyms already expanded on first use
• Vale heading-case flags when the heading already follows sentence case and only includes required acronyms or product names
• alex flags on accepted technical terms only when the term is required by the UI, appears in a literal product label, or a rewording would change the meaning. Otherwise, prefer a clearer rewrite such as run.
• node scripts/check-broken-links.mjs skips the known false positives https://marketplace.visualstudio.com/items?itemName=poolside-ai.poolside-assistant and https://poolside.poolside.local with any path under that host

If a Vale flag conflicts with an explicit rule in STYLE_GUIDE.md, report it as a likely false positive instead of treating it as a documentation issue. Report format

• One issue per item, with the file and line reference
• State what is wrong and why it matters
• Suggest a fix only when the correct answer is clear; otherwise flag and ask

Close out Before closing out, summarize any open issues the human writer needs to act on:

• Contradictions between source material, product behavior, or existing docs that were flagged but not resolved
• Coverage gaps or missing pages that emerged during the task
• Terminology that appeared unstable or inconsistently used and needs a canonical decision
• Priority or roadmap questions that surfaced during the task and affect documentation coverage or sequencing

Also consider whether anything learned, such as new documentation patterns, terminology decisions, or reusable conventions, should update AGENTS.md or docs-standards/. If so, flag it as well.

​

Default page expectations

• Include frontmatter with title and description.
• Use sentence-case headings.
• Use descriptive links.
• Use language identifiers on fenced code blocks.
• Omit $ from command examples.
• Use angle-bracket placeholders with lowercase, hyphenated names.

​

Accuracy and trust

Documentation that oversimplifies, glosses over edge cases, or reflects wishful product thinking actively harms users. The standard is not “does this sound plausible,” it is “can a user trust this to be true.”

• Do not smooth over complexity that users will actually encounter.
• Do not describe how a feature is supposed to work if you have reason to believe the behavior is inconsistent or conditional. Flag it instead.
• If product behavior contradicts what is currently documented, surface the contradiction rather than silently updating one version.
• If terminology feels unstable or inconsistently used across the product, flag it as a terminology decision the human writer should own.
• Validate meaning before phrasing. A clearer sentence is not an improvement if it makes the behavior less accurate.
• When knowledge is scattered across code, product behavior, tickets, and existing docs, turn it into one accurate explanation or explicitly note what is still unverified.

​

Uncertainty handling

If repository content, code behavior, or product details are unclear, inspect the source material first. If the answer is still unverified, insert a TODO comment inline with a specific question rather than guessing or omitting the gap. Example: {/* TODO: confirm whether X requires Y to be enabled first */}