diff --git a/.cursor/rules/create-user-documentation.mdc b/.cursor/rules/create-user-documentation.mdc deleted file mode 100644 index bffdc64b83..0000000000 --- a/.cursor/rules/create-user-documentation.mdc +++ /dev/null @@ -1,430 +0,0 @@ ---- -description: Generate or update user documentation for ValidMind software features -globs: - - "site/**/*.qmd" - - "site/**/*.yaml" - - "site/**/*.yml" -alwaysApply: false ---- - -# Create User Documentation - -Use this rule when creating new or updating existing user documentation for ValidMind software features. - -## Rules vs Skills - -This is a **Cursor Rule** (`.mdc` file), not a "skill": - -- **Rules** are file-based instructions that activate automatically based on glob patterns or can be invoked by the agent. They live in `.cursor/rules/` and provide context-aware guidance. -- **Skills** is a term sometimes used for prompt templates or reusable instructions, but Cursor's native mechanism is rules. - -This rule activates when you're working on `.qmd`, `.yaml`, or `.yml` files under `site/` and provides documentation standards and workflow guidance. - ---- - -## Workflow - -### 1. Gather Context from Typical Inputs - -Documentation updates typically start with these inputs from the writer: - -#### Shortcut Context (Primary Source) -The writer provides Shortcut story/epic IDs or links. Use these to gather: -- `stories-get-by-id` — Full story details, acceptance criteria, description -- `epics-get-by-id` — Epic overview for larger features -- `stories-search` — Find related stories in the same epic or with similar labels - -**Always check for parent epic:** When given a story ID, check if it belongs to an epic (`epic_id` field in the story). If so, fetch the epic with `epics-get-by-id` — epics often contain: -- Broader feature context and goals -- Links to backend/frontend GitHub PRs -- Related stories that may affect documentation -- Overall acceptance criteria beyond the individual story - -**Extract from Shortcut:** -- Feature requirements and acceptance criteria -- User-facing behavior descriptions -- Edge cases and limitations -- Related stories for cross-references -- GitHub PR links (often found in epic or story descriptions/comments) - -#### Backend/Frontend PRs (Implementation Details) -The writer provides PR numbers or links. Use these to understand what changed: -- `get_pull_request` — PR description, context, reviewer comments -- `get_pull_request_files` — List of changed files -- `get_file_contents` — Read specific implementation files if needed - -**Extract from PRs:** -- Actual UI changes and new fields/buttons -- API changes or new endpoints -- Configuration options -- Implementation notes from PR description - -#### Screenshots from Demos -The writer attaches screenshots showing the feature in action. Use these to: -- Verify UI element names and locations -- Understand the user flow -- Identify what needs visual documentation -- Confirm the feature matches Shortcut acceptance criteria - -#### Writer's Notes -The writer provides human context such as: -- Draft content or bullet points -- Specific sections to focus on -- Questions to address -- Audience considerations -- Links to existing docs that need updating - -#### Notion (Optional — Feature Specs) -If available, the writer may provide Notion links to feature specs: -- `notion-fetch` — Retrieve full page content -- Look for: detailed requirements, UI mockups, stakeholder context - -### 2. Choose the Appropriate Template - -Templates are available in `internal/templates/`. Choose based on content type: - -#### Task Template (`internal/templates/task.qmd`) -Step-by-step instructions for completing a specific action. -- Use for: "How to configure X", "Setting up Y", "Managing Z" -- Structure: Prerequisites → Steps → Troubleshooting → What's next -- **Title convention:** Start with a verb, nouns in plural (e.g., "Register models in the inventory") - -#### Concept Template (`internal/templates/concept.qmd`) -Understanding a feature or system. -- Use for: "What is X?", "How X works", "Understanding Y" -- Structure: Introduction → Key concepts → Examples → What's next -- **Title convention:** Nouns only, end with `-overview` if introducing a product area - -#### Reference Template (`internal/templates/reference.qmd`) -Technical specifications or API details. -- Use for: Field descriptions, configuration options, API endpoints -- Structure: Sections → Subsections → Additional Resources -- **Note:** Only use if content cannot be generated programmatically - -#### Other Templates -- `mermaid-diagrams.qmd` — For process flows and diagrams -- `tachyons-flexbox.qmd` — For responsive column layouts -- `single-source/` — For content shared between guides and training - ---- - -## Style Guide Reference - -Follow the ValidMind style guide at `site/about/contributing/style-guide/`. Key principles: - -### Voice and Tone (`voice-and-tone.qmd`) - -**Human-first approach:** -- Use **active voice** — "You'll need to review" not "The content will be reviewed by you" -- Use **common language** — Define acronyms on first use -- **Break it down** — Bulleted lists, visual aids, digestible parts - -**Inclusive and welcoming:** -- Show empathy, acknowledge user frustrations -- Focus on solutions, not problems -- Use bias-free communication -- Provide alt text for images - -**Conversational but professional:** -- Address reader directly (second person: "you") -- Use contractions where appropriate -- Avoid stiff formality - -### Conventions (`conventions.qmd`) - -**American English** spelling and grammar. - -**Titles:** -- Task titles: Start with verb, nouns in plural ("Register models in the inventory") -- Parent tasks: Use gerund ("Working with the model inventory") -- Reference titles: Name only, or end with "reference" - -**Formatting:** - -| Element | Format | Example | -|---------|--------|---------| -| UI elements (interactive) | Bold | **{{< fa cubes >}} Inventory** | -| Statuses/roles | Bubble class | `[Status Name]{.bubble}` | -| First use of terms | Italics | *Uncertainty* is defined as... | -| Code/params/files | Backticks | `.env` file, `classifier_full_suite` | -| Smallcaps UI | Smallcaps class | `[model status]{.smallcaps}` | - -**UI element bolding:** -- Bold UI elements only when the user must interact with them directly in a numbered step (e.g., "Click **Settings**"). -- Do not bold UI elements when mentioned descriptively (e.g., "tasks appear under the Tasks tab"). - -**List punctuation:** -- End list items with a period if the item contains a verb. -- List items that are noun phrases only (no verb) do not need a period. - -**Callouts:** -```markdown -::: {.callout title="Note or tip"} -Supplemental information. -::: - -::: {.callout-important title="Warning"} -Critical information or caveats. -::: -``` - -**Links:** -- Always use `.qmd` extension, not `.html` -- Use absolute paths from site root: `/guide/feature/page.qmd` -- Use margin footnotes instead of inline links in instructional text -- Use variables for product names: `{{< var validmind.platform >}}` - -**Footnotes (at end of file):** -```markdown - - -[^1]: [Register models in the inventory](/guide/model-inventory/register-models-in-inventory.qmd) - -[^2]: [Manage permissions](/guide/configuration/manage-permissions.qmd) -``` - -**Screenshots:** -```markdown -![Description](image.png){fig-alt="Detailed alt text" .screenshot} -``` - -**Responsive columns (use Tachyons, NOT CSS Grid):** -```markdown -:::: {.flex .flex-wrap .justify-around} - -::: {.w-50-ns} -Column 1 -::: - -::: {.w-50-ns} -Column 2 -::: - -:::: -``` - ---- - -## Required File Structure - -### YAML Header (Required) -```yaml ---- -# Copyright © 2023-2026 ValidMind Inc. All rights reserved. -# Refer to the LICENSE file in the root of this repository for details. -# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial -title: "Title in Sentence Case" -date: last-modified ---- -``` - -### Opening Paragraph -- One sentence describing what the page covers and why it matters -- No heading before this paragraph - -### Prerequisites Block (for tasks) -```markdown -::: {.attn} - -## Prerequisites - -- [x] {{< var link.login >}} -- [x] Additional prerequisite -- [x] Required role or permission[^1] - -::: -``` - ---- - -## Navigation Updates - -When creating new pages, update the appropriate navigation file: - -- **Sidebar navigation:** `site/guide/_sidebar.yaml`, `site/get-started/_sidebar.yaml`, etc. -- **Main config:** `site/_quarto.yml` for top-level pages -- **Listing pages:** Parent `.qmd` files with `listing:` YAML for grid layouts - -**Always add aliases when moving/renaming files:** -```yaml -aliases: - - /old/path/to/page.html -``` - ---- - -## Review Checklist - -Before finalizing: -- [ ] Copyright header present -- [ ] Title follows sentence case and naming conventions -- [ ] Prerequisites listed (for tasks) -- [ ] Steps are numbered and actionable -- [ ] UI elements are bolded with Font Awesome icons -- [ ] Links use `.qmd` extension and absolute paths -- [ ] Images have descriptive alt text and `.screenshot` class -- [ ] Footnotes for cross-references (not inline links) -- [ ] American English spelling -- [ ] Active voice throughout -- [ ] Page added to navigation (`_sidebar.yaml` or `_quarto.yml`) - ---- - -## Example Prompts - -**Creating new documentation:** -> "Create documentation for the new attestation feature. Here's the Notion spec: [URL]. The Shortcut epic is #1234." - -**Updating existing documentation:** -> "Update the model registration docs to include the new bulk import feature from PR #567." - -**From scratch with context:** -> "I need to document how users configure webhook notifications. I'll provide screenshots and the Shortcut story has acceptance criteria." - ---- - -## Training Materials (Revealjs) - -Training courses use a different format and style. Templates are in `site/training/training-templates/`. - -### Course Structure - -Each course lives in its own subdirectory: `/training/course-name/` - -A course consists of: -1. **Course registration page** (`course-registration.qmd`) — Overview and sign-up -2. **Course slides** (`course-slides.qmd`) — Revealjs presentation - -### Course Registration Template (`training-templates/course-registration.qmd`) - -```yaml ---- -title: "Course Title" -subtitle: For {{< var vm.product >}} -listing: - - id: modules - type: grid - contents: - # IMPORTANT: Use .html path for revealjs output - - path: course-slides.html - title: "Module Title" - subtitle: "Module 1" - description: "{{< fa check >}} Learning point 1
{{< fa check >}} Learning point 2" - reading-time: "30" ---- -``` - -### Course Slides Template (`training-templates/course-slides.qmd`) - -**YAML Header:** -```yaml ---- -title: "Module Title" -subtitle: "Course Name — Module # of #" -lightbox: true -format: - revealjs: - include-in-header: - - text: | - - theme: [default, ../assets/slides.scss] - slide-number: true - footer: "{{< var validmind.training >}} | [Home {{< fa person-walking-dashed-line-arrow-right >}}](/training/training.qmd)" - revealjs-plugins: - - slideover - html: - output-file: _course-slides.html - search: false -title-slide-attributes: - data-background-color: "#083E44" - data-background-image: "../assets/home-hero.svg" ---- -``` - -### Training-Specific Conventions - -**Links:** Use inline links (not footnotes) — footnotes don't display in presentation mode. - -**Section Headers:** Use background colors/images for major sections: -```markdown -# Section Title {background-color="#083E44" background-image="/assets/img/about-us-esphere.svg"} -``` - -**Interactive iFrame Embeds:** -```markdown -## {background-iframe="https://app.prod.validmind.ai/" data-preload="yes"} - -:::: {.slideover--r} -Right-aligned modal content over the live platform. -:::: -``` - -**Slideover Positions:** -- `.slideover--r` — Right-aligned -- `.slideover--l` — Left-aligned -- `.slideover--t` — Top-aligned -- `.slideover--b` — Bottom-aligned - -**Slideover Options:** -- `.auto-collapse` — Auto-collapse after 5 seconds -- `.auto-collapse-10` — Auto-collapse after 10 seconds -- `.three-quarters`, `.half`, `.third` — Width options - -**Scrollable Content:** -```markdown -## {.scrollable} - -:::: {.columns} -::: {.column width="30%"} -Summary content -::: - -::: {.column width="70%" .bl .pl4} -Detailed instructions (scrollable) -::: -:::: -``` - -**Embed Callout (within slideovers):** -```markdown -::: {.embed} -Important information styled as a nested callout. -::: -``` - -**Learning Objectives Format:** -```markdown -# Learning objectives {.center} - -_"As a {{ role }} who ... {{< var vm.product >}}, I want to learn how to {{ task A }}, {{ task B }}, and {{ task C }}."_ -``` - -**Summary Slide Format:** -```markdown -In this module, you learned how to: - -- [x] Task 1 -- [x] Task 2 -- [x] Task 3 -``` - ---- - -## MCP Tool Reference - -### Notion -- `notion-search` — Find pages/databases by keyword -- `notion-fetch` — Get full page content by URL or ID - -### Shortcut -- `stories-search` — Find stories by various filters -- `stories-get-by-id` — Get full story details -- `epics-get-by-id` — Get epic details -- `iterations-get-active` — Current sprint context - -### GitHub -- `list_pull_requests` — Find PRs by state/branch -- `get_pull_request` — Full PR details -- `get_pull_request_files` — Changed files in PR -- `list_commits` — Recent commits -- `get_file_contents` — Read specific files diff --git a/.cursor/skills/create-user-documentation/SKILL.md b/.cursor/skills/create-user-documentation/SKILL.md deleted file mode 100644 index 249cf53102..0000000000 --- a/.cursor/skills/create-user-documentation/SKILL.md +++ /dev/null @@ -1,417 +0,0 @@ ---- -name: create-user-documentation -description: Generate or update user documentation for ValidMind software features. Use when creating .qmd files, updating docs based on Shortcut stories/epics, or following ValidMind style conventions. ---- - -# Create User Documentation - -Use this skill when creating new or updating existing user documentation for ValidMind software features. - ---- - -## Workflow - -### 1. Gather Context from Typical Inputs - -Documentation updates typically start with these inputs from the writer: - -#### Shortcut Context (Primary Source) -The writer provides Shortcut story/epic IDs or links. Use these to gather: -- `stories-get-by-id` — Full story details, acceptance criteria, description -- `epics-get-by-id` — Epic overview for larger features -- `stories-search` — Find related stories in the same epic or with similar labels - -**Always check for parent epic:** When given a story ID, check if it belongs to an epic (`epic_id` field in the story). If so, fetch the epic with `epics-get-by-id` — epics often contain: -- Broader feature context and goals -- Links to backend/frontend GitHub PRs -- Related stories that may affect documentation -- Overall acceptance criteria beyond the individual story - -**Extract from Shortcut:** -- Feature requirements and acceptance criteria -- User-facing behavior descriptions -- Edge cases and limitations -- Related stories for cross-references -- GitHub PR links (often found in epic or story descriptions/comments) - -#### Backend/Frontend PRs (Implementation Details) -The writer provides PR numbers or links. Use these to understand what changed: -- `get_pull_request` — PR description, context, reviewer comments -- `get_pull_request_files` — List of changed files -- `get_file_contents` — Read specific implementation files if needed - -**Extract from PRs:** -- Actual UI changes and new fields/buttons -- API changes or new endpoints -- Configuration options -- Implementation notes from PR description - -#### Screenshots from Demos -The writer attaches screenshots showing the feature in action. Use these to: -- Verify UI element names and locations -- Understand the user flow -- Identify what needs visual documentation -- Confirm the feature matches Shortcut acceptance criteria - -#### Writer's Notes -The writer provides human context such as: -- Draft content or bullet points -- Specific sections to focus on -- Questions to address -- Audience considerations -- Links to existing docs that need updating - -#### Notion (Optional — Feature Specs) -If available, the writer may provide Notion links to feature specs: -- `notion-fetch` — Retrieve full page content -- Look for: detailed requirements, UI mockups, stakeholder context - -### 2. Choose the Appropriate Template - -Templates are available in `internal/templates/`. Choose based on content type: - -#### Task Template (`internal/templates/task.qmd`) -Step-by-step instructions for completing a specific action. -- Use for: "How to configure X", "Setting up Y", "Managing Z" -- Structure: Prerequisites → Steps → Troubleshooting → What's next -- **Title convention:** Start with a verb, nouns in plural (e.g., "Register models in the inventory") - -#### Concept Template (`internal/templates/concept.qmd`) -Understanding a feature or system. -- Use for: "What is X?", "How X works", "Understanding Y" -- Structure: Introduction → Key concepts → Examples → What's next -- **Title convention:** Nouns only, end with `-overview` if introducing a product area - -#### Reference Template (`internal/templates/reference.qmd`) -Technical specifications or API details. -- Use for: Field descriptions, configuration options, API endpoints -- Structure: Sections → Subsections → Additional Resources -- **Note:** Only use if content cannot be generated programmatically - -#### Other Templates -- `mermaid-diagrams.qmd` — For process flows and diagrams -- `tachyons-flexbox.qmd` — For responsive column layouts -- `single-source/` — For content shared between guides and training - ---- - -## Style Guide Reference - -Follow the ValidMind style guide at `site/about/contributing/style-guide/` in the documentation repo. Key principles summarized below — refer to the full guide for details. - -### Voice and Tone - -**Human-first approach:** -- Use **active voice** — "You'll need to review" not "The content will be reviewed by you" -- Use **common language** — Define acronyms on first use -- **Break it down** — Bulleted lists, visual aids, digestible parts - -**Inclusive and welcoming:** -- Show empathy, acknowledge user frustrations -- Focus on solutions, not problems -- Use bias-free communication -- Provide alt text for images - -**Conversational but professional:** -- Address reader directly (second person: "you") -- Use contractions where appropriate -- Avoid stiff formality - -### Conventions - -**American English** spelling and grammar. - -**Titles:** -- Task titles: Start with verb, nouns in plural ("Register models in the inventory") -- Parent tasks: Use gerund ("Working with the model inventory") -- Reference titles: Name only, or end with "reference" - -**Formatting:** - -| Element | Format | Example | -|---------|--------|---------| -| UI elements (interactive) | Bold | **{{< fa cubes >}} Inventory** | -| Statuses/roles | Bubble class | `[Status Name]{.bubble}` | -| First use of terms | Italics | *Uncertainty* is defined as... | -| Code/params/files | Backticks | `.env` file, `classifier_full_suite` | -| Smallcaps UI | Smallcaps class | `[model status]{.smallcaps}` | - -**UI element bolding:** -- Bold UI elements only when the user must interact with them directly in a numbered step (e.g., "Click **Settings**"). -- Do not bold UI elements when mentioned descriptively (e.g., "tasks appear under the Tasks tab"). - -**List punctuation:** -- End list items with a period if the item contains a verb. -- List items that are noun phrases only (no verb) do not need a period. - -**Callouts:** -```markdown -::: {.callout title="Note or tip"} -Supplemental information. -::: - -::: {.callout-important title="Warning"} -Critical information or caveats. -::: -``` - -**Links:** -- Always use `.qmd` extension, not `.html` -- Use absolute paths from site root: `/guide/feature/page.qmd` -- Use margin footnotes instead of inline links in instructional text -- Use variables for product names: `{{< var validmind.platform >}}` - -**Footnotes (at end of file):** -```markdown - - -[^1]: [Register models in the inventory](/guide/model-inventory/register-models-in-inventory.qmd) - -[^2]: [Manage permissions](/guide/configuration/manage-permissions.qmd) -``` - -**Screenshots:** -```markdown -![Description](image.png){fig-alt="Detailed alt text" .screenshot} -``` - -**Responsive columns (use Tachyons, NOT CSS Grid):** -```markdown -:::: {.flex .flex-wrap .justify-around} - -::: {.w-50-ns} -Column 1 -::: - -::: {.w-50-ns} -Column 2 -::: - -:::: -``` - ---- - -## Required File Structure - -### YAML Header (Required) -```yaml ---- -# Copyright © 2023-2026 ValidMind Inc. All rights reserved. -# Refer to the LICENSE file in the root of this repository for details. -# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial -title: "Title in Sentence Case" -date: last-modified ---- -``` - -### Opening Paragraph -- One sentence describing what the page covers and why it matters -- No heading before this paragraph - -### Prerequisites Block (for tasks) -```markdown -::: {.attn} - -## Prerequisites - -- [x] {{< var link.login >}} -- [x] Additional prerequisite -- [x] Required role or permission[^1] - -::: -``` - ---- - -## Navigation Updates - -When creating new pages, update the appropriate navigation file: - -- **Sidebar navigation:** `site/guide/_sidebar.yaml`, `site/get-started/_sidebar.yaml`, etc. -- **Main config:** `site/_quarto.yml` for top-level pages -- **Listing pages:** Parent `.qmd` files with `listing:` YAML for grid layouts - -**Always add aliases when moving/renaming files:** -```yaml -aliases: - - /old/path/to/page.html -``` - ---- - -## Review Checklist - -Before finalizing: -- [ ] Copyright header present -- [ ] Title follows sentence case and naming conventions -- [ ] Prerequisites listed (for tasks) -- [ ] Steps are numbered and actionable -- [ ] UI elements are bolded with Font Awesome icons -- [ ] Links use `.qmd` extension and absolute paths -- [ ] Images have descriptive alt text and `.screenshot` class -- [ ] Footnotes for cross-references (not inline links) -- [ ] American English spelling -- [ ] Active voice throughout -- [ ] Page added to navigation (`_sidebar.yaml` or `_quarto.yml`) - ---- - -## Example Prompts - -**Creating new documentation:** -> "Create documentation for the new attestation feature. Here's the Notion spec: [URL]. The Shortcut epic is #1234." - -**Updating existing documentation:** -> "Update the model registration docs to include the new bulk import feature from PR #567." - -**From scratch with context:** -> "I need to document how users configure webhook notifications. I'll provide screenshots and the Shortcut story has acceptance criteria." - ---- - -## Training Materials (Revealjs) - -Training courses use a different format and style. Templates are in `site/training/training-templates/`. - -### Course Structure - -Each course lives in its own subdirectory: `/training/course-name/` - -A course consists of: -1. **Course registration page** (`course-registration.qmd`) — Overview and sign-up -2. **Course slides** (`course-slides.qmd`) — Revealjs presentation - -### Course Registration Template (`training-templates/course-registration.qmd`) - -```yaml ---- -title: "Course Title" -subtitle: For {{< var vm.product >}} -listing: - - id: modules - type: grid - contents: - # IMPORTANT: Use .html path for revealjs output - - path: course-slides.html - title: "Module Title" - subtitle: "Module 1" - description: "{{< fa check >}} Learning point 1
{{< fa check >}} Learning point 2" - reading-time: "30" ---- -``` - -### Course Slides Template (`training-templates/course-slides.qmd`) - -**YAML Header:** -```yaml ---- -title: "Module Title" -subtitle: "Course Name — Module # of #" -lightbox: true -format: - revealjs: - include-in-header: - - text: | - - theme: [default, ../assets/slides.scss] - slide-number: true - footer: "{{< var validmind.training >}} | [Home {{< fa person-walking-dashed-line-arrow-right >}}](/training/training.qmd)" - revealjs-plugins: - - slideover - html: - output-file: _course-slides.html - search: false -title-slide-attributes: - data-background-color: "#083E44" - data-background-image: "../assets/home-hero.svg" ---- -``` - -### Training-Specific Conventions - -**Links:** Use inline links (not footnotes) — footnotes don't display in presentation mode. - -**Section Headers:** Use background colors/images for major sections: -```markdown -# Section Title {background-color="#083E44" background-image="/assets/img/about-us-esphere.svg"} -``` - -**Interactive iFrame Embeds:** -```markdown -## {background-iframe="https://app.prod.validmind.ai/" data-preload="yes"} - -:::: {.slideover--r} -Right-aligned modal content over the live platform. -:::: -``` - -**Slideover Positions:** -- `.slideover--r` — Right-aligned -- `.slideover--l` — Left-aligned -- `.slideover--t` — Top-aligned -- `.slideover--b` — Bottom-aligned - -**Slideover Options:** -- `.auto-collapse` — Auto-collapse after 5 seconds -- `.auto-collapse-10` — Auto-collapse after 10 seconds -- `.three-quarters`, `.half`, `.third` — Width options - -**Scrollable Content:** -```markdown -## {.scrollable} - -:::: {.columns} -::: {.column width="30%"} -Summary content -::: - -::: {.column width="70%" .bl .pl4} -Detailed instructions (scrollable) -::: -:::: -``` - -**Embed Callout (within slideovers):** -```markdown -::: {.embed} -Important information styled as a nested callout. -::: -``` - -**Learning Objectives Format:** -```markdown -# Learning objectives {.center} - -_"As a {{ role }} who ... {{< var vm.product >}}, I want to learn how to {{ task A }}, {{ task B }}, and {{ task C }}."_ -``` - -**Summary Slide Format:** -```markdown -In this module, you learned how to: - -- [x] Task 1 -- [x] Task 2 -- [x] Task 3 -``` - ---- - -## MCP Tool Reference - -### Notion -- `notion-search` — Find pages/databases by keyword -- `notion-fetch` — Get full page content by URL or ID - -### Shortcut -- `stories-search` — Find stories by various filters -- `stories-get-by-id` — Get full story details -- `epics-get-by-id` — Get epic details -- `iterations-get-active` — Current sprint context - -### GitHub -- `list_pull_requests` — Find PRs by state/branch -- `get_pull_request` — Full PR details -- `get_pull_request_files` — Changed files in PR -- `list_commits` — Recent commits -- `get_file_contents` — Read specific files diff --git a/.gitignore b/.gitignore index 7bd12fef76..de8667d222 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,7 @@ site/validmind-docs.yaml # Python API docs are now generated on the fly site/validmind + +# Cursor rules +.cursor/rules/ +.cursor/skills/ \ No newline at end of file diff --git a/README.md b/README.md index cacece26aa..f87db708af 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ You need: - [Quarto CLI](https://quarto.org/docs/get-started/) - The Quarto extension for your IDE, such as [VS Code](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) +- To use Cursor to author documentation, the [`create-user-documentation`](https://github.com/validmind/skills/tree/main/create-user-documentation) skill - For Windows operating systems, install the `make` command via [Cygwin](https://cygwin.com/install.html) ### Additional dependencies @@ -40,40 +41,28 @@ Some interactive tables, such as our breaking changes and dependency history rel If you are creating a pull request, test your changes by rendering or previewing the site. Note that if this is your first time contributing, you will be asked to sign a contributor license agreement (CLA). -### Using the Cursor documentation rule +### Using the Cursor documentation skill -If you use [Cursor](https://cursor.sh), we have a rule at `.cursor/rules/create-user-documentation.mdc` that helps generate and update documentation by pulling context from multiple sources. - -#### Setup - -The rule requires MCP (Model Context Protocol) servers configured in your `~/.cursor/mcp.json`: - -- **Shortcut MCP** — For story/epic context and acceptance criteria -- **GitHub MCP** — For PR details and implementation changes -- **Notion MCP** (optional) — For feature specifications - -See [Cursor's MCP documentation](https://docs.cursor.com/context/model-context-protocol) for setup instructions. - -#### How to use - -Start a new Cursor chat and provide your typical inputs: +If you use [Cursor](https://cursor.sh), the [`create-user-documentation`](https://github.com/validmind/skills/tree/main/create-user-documentation) skill helps you author content. Start a new Cursor chat and provide your inputs: ``` Create documentation for the new webhook notifications feature. The Shortcut story is #1234. I'll attach some screenshots. ``` -The rule will guide the AI to: +The skill guides the AI to: 1. Fetch the Shortcut story for requirements and acceptance criteria 2. Look up linked GitHub PRs (Shortcut stories often reference backend/frontend PRs) 3. Use your screenshots to verify UI elements 4. Apply ValidMind style guide conventions 5. Generate documentation using the appropriate template +You can also invoke the skill explicitly by typing `/create-user-documentation` in Agent chat. + #### Tips - **Provide the epic ID if you have it:** Epics often contain richer context than individual stories — including links to backend/frontend PRs, related stories, and broader feature goals. If you know the epic ID, include it for better results. -- **Finding PRs from Shortcut:** Shortcut stories and epics typically have GitHub PRs linked in descriptions or comments. The AI will automatically look up the parent epic when given a story ID to find these links. +- **Finding PRs from Shortcut:** Shortcut stories and epics typically have GitHub PRs linked in descriptions or comments. The AI automatically looks up the parent epic when given a story ID to find these links. - **Provide screenshots:** Attach screenshots from demos to help the AI verify UI element names and user flows. - **Include your notes:** Add bullet points or draft content to guide the output focus. - **Specify the doc type:** Mention if you need a task (how-to), concept (explanation), or reference doc. diff --git a/site/Makefile b/site/Makefile index d46f551947..d944db545f 100644 --- a/site/Makefile +++ b/site/Makefile @@ -326,6 +326,8 @@ notebooks: @rm -rf $(DEST_DIR_NB)/templates @echo "Copying _metadata.yml into notebooks/ ..." @cp developer/_metadata.yml $(DEST_DIR_NB)/_metadata.yml + @echo "Updating developer/_sidebar.yaml with code_samples directories ..." + @python scripts/update_code_samples_sidebar.py @echo "Zip up notebooks.zip ..." @zip -r notebooks.zip $(DEST_DIR_NB) > /dev/null 2>&1 diff --git a/site/developer/_sidebar.yaml b/site/developer/_sidebar.yaml index 3cbeea5b45..3b1680ea69 100644 --- a/site/developer/_sidebar.yaml +++ b/site/developer/_sidebar.yaml @@ -53,7 +53,27 @@ website: - text: "Notebooks" - text: "Code samples" file: developer/samples-jupyter-notebooks.qmd - contents: "notebooks/code_samples/**" + contents: + - section: "Agents" + contents: "notebooks/code_samples/agents/**" + - section: "Capital markets" + contents: "notebooks/code_samples/capital_markets/**" + - section: "Code explainer" + contents: "notebooks/code_samples/code_explainer/**" + - section: "Credit risk" + contents: "notebooks/code_samples/credit_risk/**" + - section: "Custom tests" + contents: "notebooks/code_samples/custom_tests/**" + - section: "Model validation" + contents: "notebooks/code_samples/model_validation/**" + - section: "NLP and LLM" + contents: "notebooks/code_samples/nlp_and_llm/**" + - section: "Ongoing monitoring" + contents: "notebooks/code_samples/ongoing_monitoring/**" + - section: "Regression" + contents: "notebooks/code_samples/regression/**" + - section: "Time series" + contents: "notebooks/code_samples/time_series/**" - text: "---" - text: "Reference" - text: "{{< var validmind.api >}}" diff --git a/site/guide/integrations/configure-connections.qmd b/site/guide/integrations/configure-connections.qmd index 587b3b88b1..230216cf1f 100644 --- a/site/guide/integrations/configure-connections.qmd +++ b/site/guide/integrations/configure-connections.qmd @@ -108,19 +108,18 @@ Required configuration details: ### GitLab - -A DevOps platform that hosts code, runs pipelines, and manages team collaboration. +Synchronize GitLab model registry with ValidMind model inventory for comprehensive model tracking. Required configuration details: **[project id]{.smallcaps}** -: The GitLab project or group path that contains the ML repository to sync. +: The GitLab project ID or path containing ML models (required). **[gitlab instance url]{.smallcaps}** (optional) -: Blank for gitlab.com or the self-hosted URL. +: Leave empty to use GitLab.com, or enter your self-hosted GitLab URL. **[personal access token]{.smallcaps}** -: A PAT secret that includes the `api` or `read_api` scope. +: Select a secret containing your GitLab Personal Access Token with `api` or `read_api` scope. ### Custom diff --git a/site/guide/integrations/integrations-examples-gitlab.png b/site/guide/integrations/integrations-examples-gitlab.png new file mode 100644 index 0000000000..ccc332dab6 Binary files /dev/null and b/site/guide/integrations/integrations-examples-gitlab.png differ diff --git a/site/guide/integrations/integrations-examples.qmd b/site/guide/integrations/integrations-examples.qmd index 3bec221b61..1bc9ebd66f 100644 --- a/site/guide/integrations/integrations-examples.qmd +++ b/site/guide/integrations/integrations-examples.qmd @@ -14,6 +14,7 @@ Adapt these usage examples for your own workflows or connections to interact wit - [Add webhook step triggers](#add-webhook-step-triggers) - [Synchronize models with AWS SageMaker](#synchronize-models-with-aws-sagemaker) - [Synchronize models with AWS Bedrock](#synchronize-models-with-aws-bedrock) +- [Synchronize models with GitLab](#synchronize-models-with-gitlab) ::: {.attn} @@ -357,6 +358,62 @@ This builds a complete dependency graph showing how your AI applications relate 9. Click **Link Model**. +### Synchronize models with GitLab + +Synchronize GitLab model registry with ValidMind model inventory for comprehensive model tracking. + +#### Configure the connection + +::: {.column-margin} +![Configure GitLab connection](integrations-examples-gitlab.png){width=80% fig-alt="Screenshot of the Configure GitLab dialog showing fields for integration name, description, project ID, GitLab instance URL, personal access token, and initial status." .screenshot} +::: + +1. In the left sidebar, click **{{< fa gear >}} Settings**. + +2. Under Integrations, select **Connections**. + +3. Click **{{< fa plus >}} Add Connection**. + +4. In the modal that opens, select **GitLab**. + +5. Complete: + + - **[integration name]{.smallcaps}** — How other admins can identify the connection. + - **[description]{.smallcaps}** (optional) — The intended usage or additional details. + - **[project id]{.smallcaps}** — The GitLab project ID or path containing ML models (required). + - **[gitlab instance url]{.smallcaps}** (optional) — Leave empty to use GitLab.com, or enter your self-hosted GitLab URL. + - **[personal access token]{.smallcaps}** — Select a secret containing your GitLab Personal Access Token with `api` or `read_api` scope. + - **[initial status]{.smallcaps}** — Set to `Operational` to enable immediately or `Disabled` if you plan to finish setup later. + +6. Click **Save Integration**. + +7. Test the connection: + + a. Hover over the GitLab connection you just created. + b. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa circle-check >}} Test Connection**. + + If the test is successful, the message **{{< fa check-circle >}} Connection successful** displays. + +#### Link the models + +1. In the left sidebar, click **{{< fa cubes >}} Inventory**. + +2. Select a model by clicking on it or find your model by applying a filter or searching for it.[^15] + +3. Scroll down until you locate the **GitLab** connection box in the right sidebar. + +4. Hover over the GitLab box. + +5. When the **{{< fa ellipsis-vertical >}}** menu appears, click on it and select **{{< fa link >}} Link Model**. + +6. In the modal that opens, click the [select model]{.smallcaps} dropdown to pick the GitLab model to link. + +7. Optional: Click **Test Connection** to ensure the connection is working as expected. + + If the test is successful, the message **{{< fa check-circle >}} Connection Test Successful** displays. + +8. Click **Link Model**. + [^1]: [Manage permissions](/guide/configuration/manage-permissions.qmd) @@ -385,4 +442,6 @@ This builds a complete dependency graph showing how your AI applications relate [^13]: [Working with the model inventory](/guide/model-inventory/working-with-model-inventory.qmd#search-filter-and-sort-models) -[^14]: [Working with the model inventory](/guide/model-inventory/working-with-model-inventory.qmd#search-filter-and-sort-models) \ No newline at end of file +[^14]: [Working with the model inventory](/guide/model-inventory/working-with-model-inventory.qmd#search-filter-and-sort-models) + +[^15]: [Working with the model inventory](/guide/model-inventory/working-with-model-inventory.qmd#search-filter-and-sort-models) \ No newline at end of file diff --git a/site/scripts/update_code_samples_sidebar.py b/site/scripts/update_code_samples_sidebar.py new file mode 100644 index 0000000000..c9d31fa5d3 --- /dev/null +++ b/site/scripts/update_code_samples_sidebar.py @@ -0,0 +1,94 @@ +# Copyright © 2023-2026 ValidMind Inc. All rights reserved. +# Refer to the LICENSE file in the root of this repository for details. +# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial +""" +Update developer/_sidebar.yaml so the Code samples entry lists each +subdirectory of notebooks/code_samples/ explicitly (with wildcards), +in alphabetical order, with fixed capitalization for NLP and LLM. + +Run from the site/ directory, e.g.: + cd site && python scripts/update_code_samples_sidebar.py +""" + +import os +from pathlib import Path + + +# Display title for directories that need fixed capitalization (e.g. acronyms) +SPECIAL_TITLES = { + "nlp_and_llm": "NLP and LLM", +} + + +def dir_to_title(dirname: str) -> str: + """Convert directory name to sidebar display title (sentence-style capitalization).""" + if dirname in SPECIAL_TITLES: + return SPECIAL_TITLES[dirname] + return dirname.replace("_", " ").capitalize() + + +def main() -> None: + # Run from site/ or repo root + cwd = Path.cwd() + if (cwd / "notebooks" / "code_samples").is_dir(): + base = cwd + elif (cwd / "site" / "notebooks" / "code_samples").is_dir(): + base = cwd / "site" + else: + raise SystemExit("Run from site/ or repo root (e.g. cd site && python scripts/update_code_samples_sidebar.py)") + code_samples = base / "notebooks" / "code_samples" + sidebar_path = base / "developer" / "_sidebar.yaml" + + if not code_samples.is_dir(): + raise SystemExit(f"Directory not found: {code_samples}") + if not sidebar_path.is_file(): + raise SystemExit(f"Sidebar file not found: {sidebar_path}") + + subdirs = sorted( + d for d in os.listdir(code_samples) + if (code_samples / d).is_dir() + ) + + # Build the new contents block (YAML). Use "section" so Quarto renders + # expandable accordion items; "text" alone does not expand. + lines = [ + ' contents:', + ] + for d in subdirs: + title = dir_to_title(d) + lines.append(f' - section: "{title}"') + lines.append(f' contents: "notebooks/code_samples/{d}/**"') + + new_block = "\n".join(lines) + + text = sidebar_path.read_text() + # Replace either the single wildcard or an existing expanded block + old_single = ' contents: "notebooks/code_samples/**"' + if old_single in text: + text = text.replace(old_single, new_block, 1) + else: + # Find the code_samples contents block and replace it (multi-line) + import re + # Match from " contents:" through all following lines that are + # " - ..." or " contents: ..." for code_samples + pattern = re.compile( + r'( - text: "Code samples"\n' + r' file: developer/samples-jupyter-notebooks\.qmd\n)' + r' contents:\n' + r'( - (?:text|section): "[^"]+"\n' + r' contents: "notebooks/code_samples/[^"]+\*\*"\n)*', + re.MULTILINE, + ) + match = pattern.search(text) + if not match: + raise SystemExit( + "Could not find Code samples contents block in sidebar. " + "Has the sidebar format changed?" + ) + text = text[: match.start()] + match.group(1) + new_block + "\n" + text[match.end() :] + sidebar_path.write_text(text) + print(f"Updated {sidebar_path} with {len(subdirs)} code sample directories.") + + +if __name__ == "__main__": + main()