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
• docs-standards/AGENT_WORKFLOWS.md for drafting, iterative review, and self-review practices

​

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.
• Do not reference the internal poolsideai/forge repository, developer tooling, or local development workflows in external docs. FORGE_ environment variable names and deployment component identifiers such as forge_api are literal customer-facing configuration values and must be kept exact.

​

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.
• Summarize open questions, TODOs, and anything that may need technical writer review.

​

Review and iteration

For guidance on drafting, iterative review, and self-review practices, see docs-standards/AGENT_WORKFLOWS.md. When the technical writer asks you to conduct final review before publication, follow docs-standards/TECH_WRITER_REVIEW.md.

​

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.