Create userguide

[MaximumTrainer]

Role: You are an expert Technical Writer specializing in Developer Experience (DX) and automated documentation.

Task: Create a comprehensive, Markdown-formatted "User Setup & Activity Guide" for the OpenFactstore website (https://github.com/MaximumTrainer/OpenFactstore).

Context: We are using a "Documentation-as-Code" approach. The screenshots for this guide are automatically generated by a Playwright test suite that runs during our CI/CD pipeline. These screenshots are stored in the /docs/public/screenshots/ directory of the repository.

Inputs to Analyze:

1. Read the README.md and any existing architecture docs to understand the core purpose of OpenFactstore.
2. Analyze the Playwright test files (found in /tests or similar) to identify key user flows (e.g., account creation, fact ingestion, searching, and workspace management).
3. Identify specific page.screenshot({ path: '...' }) calls within the tests to determine which visual states are available.

Requirements for the Guide:

1. Introduction: A brief overview of what a user can achieve with OpenFactstore.
2. Prerequisites: List what a user needs before starting (e.g., environment variables, account types).
3. Step-by-Step Walkthrough: For every key activity identified in the Playwright tests:
   • Activity Title: (e.g., "Creating Your First Fact Store")
   • Description: A clear explanation of why and when a user performs this action.
   • Action Steps: Numbered instructions mirroring the Playwright test logic.
   • Visual Reference: Insert a Markdown image link using the naming convention found in the tests (e.g., ![Description of Screen](./screenshots/filename.png)).
4. UI Descriptions: For every screenshot, provide a "Key Elements" section describing specific buttons, inputs, or data displays shown in that specific view.
5. Troubleshooting: A section based on common failure states handled in the test suite.

Tone and Style:

• Use active, helpful language (e.g., "Navigate to..." instead of "The user should go to...").
• Keep formatting clean and compatible with Docusaurus, MkDocs, or Astro Starlight.
• Use callouts (Note/Warning/Tip) for critical configuration steps.

Output: Generate the full Markdown content for user-guide.md.

Strategy for Implementation (The "Pipeline" Part)

To make this work effectively with your Playwright/Documentation setup, I recommend the following workflow:

1. Standardize your Playwright Tests

In your Playwright tests, use descriptive naming for your screenshots so the AI can easily map them.
Example:

test('user can create a new fact', async ({ page }) => {
  await page.goto('/dashboard');
  // ... steps ...
  await page.screenshot({ path: 'docs/public/screenshots/create-fact-screen.png' });
});

2.Github Action

If you want to automate this entirely, you can create a GitHub Action that:

1. Runs Playwright tests to refresh screenshots.
2. Sends the updated Test Code + Manifest to an LLM via API using the prompt provided above.
3. Commit the updated user-guide.md back to the repo.