add claude.md (#1760)

Author: Slashek

.gitignore

@@ -13,6 +13,7 @@ app/assets/*
 !app/assets/fonts/
 !app/assets/vendor/
 .lighthouseci/
+.claude
 
 
 modules/graphql/public/views/pages/**/*.html

CLAUDE.md

@@ -0,0 +1,172 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is the platformOS documentation site, built on the platformOS platform itself. The site uses Liquid templates, GraphQL queries, and JavaScript/CSS for a static documentation experience. The documentation is stored as Liquid files in `app/views/pages/` and organized by topic.
+
+## Key Architecture
+
+### Application Structure
+
+- **app/**: Main platformOS application directory
+  - **views/pages/**: 540+ documentation pages in Liquid format, organized by topic (developer-guide, best-practices, api-reference, etc.)
+  - **views/layouts/**: Layout templates (application.liquid is the main layout)
+  - **views/partials/**: Reusable components organized by feature area
+  - **graphql/**: GraphQL query files for data fetching
+  - **lib/**: Liquid library files (queries and commands)
+  - **model_schemas/**: Data model definitions (YAML)
+  - **assets/**: Compiled JS/CSS output (generated by webpack)
+  - **config.yml**: platformOS configuration
+
+- **modules/**: platformOS modules with their own structure
+  - **core/**: Core module with generators for scaffolding
+  - **graphql/**: GraphQL documentation module
+  - **openai/**: OpenAI integration module
+
+- **src/**: Source assets (pre-webpack)
+  - **app.js**: Main JavaScript entry point (imports features lazily via webpack chunks)
+  - **app.css**: Main CSS entry point (Tailwind + custom components)
+  - **js/**: JavaScript modules (search, syntax highlighting, feedback, etc.)
+  - **css/**: Custom CSS organized by layout/components
+
+### Build System
+
+The project uses Webpack with:
+- **esbuild-loader** for fast JS transpilation
+- **PostCSS + Tailwind CSS** for styling
+- **Mini CSS Extract Plugin** for CSS extraction
+- Code splitting with chunkhash for caching
+- Two entry points: `app` (main site) and `graphql` (GraphQL docs module)
+
+### platformOS Integration
+
+This is a platformOS application, meaning:
+- **pos-cli** is used for deployment and syncing
+- **Liquid templates** are the primary templating language
+- **GraphQL** is used for querying data
+- **Model schemas** (YAML) define data structures
+- Configuration in `.pos` file defines environments (local, staging, production)
+
+## Common Commands
+
+### Development
+
+```bash
+npm ci                 # Install dependencies (use ci for clean installs)
+npm start              # Run webpack watch + pos-cli sync with livereload
+```
+
+**Important**: `npm start` requires pos-cli to be installed globally and configured with proper credentials in `.pos` file.
+
+### Building
+
+```bash
+npm run build          # Build production assets (webpack) and prepare inline CSS/JS
+npm run build:graphql  # Generate GraphQL documentation from schema
+```
+
+The build process:
+1. Cleans old assets (`prebuild`)
+2. Runs webpack in production mode
+3. Copies built assets to partials for inline inclusion (`postbuild`)
+
+### Testing
+
+```bash
+npm test               # Run CodeceptJS end-to-end tests
+```
+
+Tests use Puppeteer and are configured in `codecept.conf.js`. They require `MPKIT_URL` environment variable to be set.
+
+### Deployment
+
+```bash
+npm run deploy         # Build assets and deploy to platformOS via pos-cli
+```
+
+Deployment target depends on pos-cli configuration. Use `-e <environment>` flag with pos-cli for specific environments.
+
+## Development Workflow
+
+### Working with Documentation Pages
+
+Documentation pages are Liquid files in `app/views/pages/`. When creating new documentation:
+
+1. Check if a template exists in `app/views/pages/doc-templates/` that matches your content type
+2. Follow the existing directory structure (by feature area)
+3. Pages are automatically indexed for search via GraphQL queries
+4. Use frontmatter metadata for page configuration (title, converter, etc.)
+
+### Working with Assets
+
+1. **Edit source files** in `src/js/` or `src/css/` (never edit files in `app/assets/` directly)
+2. Run `npm start` for live reloading during development
+3. The build copies compiled assets to `app/views/partials/css/source/` and `app/views/partials/js/source/` for inline inclusion
+
+### Working with GraphQL
+
+- GraphQL queries are stored in `app/graphql/` as `.graphql` files
+- They can be invoked from Liquid templates using GraphQL tags
+- The `build:graphql` script generates documentation from the platformOS GraphQL schema
+
+### Working with Modules
+
+Modules are self-contained feature sets:
+- Each module has its own directory structure (similar to `app/`)
+- Core module includes Yeoman generators for scaffolding
+- Modules are versioned independently
+
+## Style Guide
+
+The project uses:
+- **Tailwind CSS** with custom theme configuration in `tailwind.config.js`
+- Custom platformOS design tokens (pos-blue, pos-darkblue, etc.)
+- **Gotham** font family
+- ESLint for JavaScript (`.eslintrc.json`)
+- Editor config (`.editorconfig`)
+
+## GraphQL Documentation Generation
+
+The GraphQL docs are auto-generated from the platformOS schema:
+
+1. Script fetches the latest schema from the platform
+2. `@platformos/graphql-docs-markdown` converts schema to Liquid pages
+3. Pages are generated in `modules/graphql/public/views/pages/api-reference/graphql/`
+4. Navigation is updated in `app/views/partials/shared/nav/graphql-navigation.liquid`
+
+## Testing Architecture
+
+CodeceptJS tests in `tests/codecept/`:
+- Use Puppeteer for browser automation
+- Test key features: navigation, search, syntax highlighting, metadata, etc.
+- Custom locators via `data-test` attributes
+- Tests retry on failure (max 3 reruns)
+- Screenshots captured on failure
+
+## CI/CD
+
+GitHub Actions workflow (`.github/workflows/`):
+1. Deploy to staging on push to master
+2. Run tests against staging
+3. Deploy to production if tests pass
+
+The workflow uses secrets for MPKIT_URL, MPKIT_EMAIL, and MPKIT_TOKEN.
+
+## Important Files
+
+- **package.json**: Defines all npm scripts and dependencies
+- **.pos**: Environment configuration for pos-cli (contains tokens)
+- **webpack.config.js**: Asset bundling configuration
+- **tailwind.config.js**: Design system configuration
+- **app/config.yml**: platformOS application configuration
+- **codecept.conf.js**: Test suite configuration
+
+## Liquid Conventions
+
+- Use `{%- render -%}` for partials to control whitespace
+- Use `{% include %}` when you need to pass context variables
+- GraphQL queries are executed with `{% graphql %}` tag
+- Forms are rendered with `{% include_form %}`
+- Layouts use `{% yield %}` for content injection